gemtext

どのようなものか

gemtextはGeminiプロトコルの文書形式です。プレーンなUTF-8テキストで、
各行の先頭文字が種類を決めるため、クライアントは上から下への一回の処
理でページ全体を表示できます。仕様はGeminiハイパーテキスト形式と呼
び、サーバーはメディアタイプ`text/gemini`を付け、ファイルの拡張子は
慣例で`.gmi`です。

行は六種類です。`=>`で始まる行はリンクで、絶対または相対アドレスと、
その後の任意のラベルからなります。バッククォート三つの行で整形済み
モードを切り替え、その二行に挟まれた内容は等幅フォントで書いたとおり
に表示します。ハッシュ記号一つから三つで見出し、アスタリスクと空白で
リスト項目、大なり記号で引用を表します。ほかは通常の本文で、クライア
ントが表示先の画面幅に合わせて折り返します。

```text
i# 現地の記録		engineer.company	70

本文一行は、長さによらず一段落です。クライアントが折り返します。

i=> /archive/ 以前の記録		engineer.company	70
i=> gemini://example.org/ 別の場所のカプセル		engineer.company	70

i* リストの項目		engineer.company	70
> 引用した一行
```

仕様はこの六種類を二つの群に分けています。すべてのクライアントが必ず
扱う基本の三種類は、本文、リンク、整形済みモードの切り替えです。残る
三種類は、最小限のクライアントなら通常のテキストとして表示してもかま
いません。形式はこれだけです。太字、斜体、表、本文中の画像、入れ子は
なく、文の途中の単語だけをクリック可能にする方法もありません。構文解
析器が持つ状態は、整形済みブロック内かどうかの一ビットだけです。

よく比較されるのは、一見似たMarkdownです。違いは用途にあります。
Markdownファイルは別のものへ変換する原稿ですが、gemtextはすでに完成
した文書で、読者のクライアントだけが描画します。リンクを独立した行に
置くという構造上の習慣は、古いGopherメニューから借りています。

なぜ重要なのか

gemtextを選ぶことは、ページを誰が制御するかを選ぶことです。作者が決
めるのは、どの行が見出しやリンクで、どこがコードかという構造です。そ
れ以外、フォント、行の長さ、色、間隔、見出しを目次にするかは、読者の
クライアントが決めます。仕様も、作者が表示を精密に制御するための形式
ではないと明記します。この制約で負担が軽くなる運営者もいれば、それだ
けで採用を見送る運営者もいます。一ページでも変換する前に、自分がどち
らに当てはまるかを確かめておく方がよいでしょう。

負担が減るのは、不要になるものがあるためです。gemtextのページには、
スタイルシート、スクリプト、ウェブフォント、Cookie通知、追跡ピクセル
がありません。更新が必要なのは文章だけです。ページは小さく、手でもす
ぐ書けます。リンク自体が何かを取得することもありません。仕様は、リン
クを表示するだけのためにネットワーク接続を開くことを禁じます。読者に
知らせず第三者の画像やフォントを読み込むことはできません。

代償も明確です。Geminiクライアントを使う人にしか届かず、ウェブに比べ
読者は少数です。フォームはなく、カプセルが入力を求める唯一の方法は、
文書内の仕組みではなく、プロトコルのステータスコードです。文章は文中
リンクなしで通じなければなりません。HTML用の「詳細は料金ページをご覧
ください」は、言葉だけ残り、その場でたどるリンクを失います。gemtext
では、リンクが次の行にあっても意味が通じる文を書く必要があります。

そのため、多くの組織に現実的なのは、ウェブサイトの代わりではなく、同
じ原稿とビルドからgemtextも提供することです。この捉え方なら、少ない
費用で加えられ、文章の検査にもなります。本文とリンクの行が並ぶだけで
も明快なら、構造は初めから言葉にあったのです。

実際の活用例

このサイトはHTMLとともにgemtextでも公開します。ターミナルでEngineer
は、`gemini://engineer.company/`を示し、全ページがこの形式でも存在す
ると説明します。読むクライアントは、ターミナルのAmfora、Lagrange、
Bombadilloと、ウィンドウのCastor、Kristallです。理由も述べます。一回
のデプロイで書く一つのフォルダーをすべての入口が読むため、gemtext版
がHTMLとずれることはありません。gemtextでも読みやすいページは、構造
を見た目だけで作っていないページです。

作り方は、サイトをGeminiとGopherへ複製した説明にあります。gemtextは
同じビルドの出力形式で、別のツールチェーンではありません。サイト生成
ツールに独自のメディアタイプと出力形式を設定し、すべてのページ、セク
ション、分類語について、HTML版とMarkdown版に加えてGemini文書も生成す
るようにしました。記録された実装段階では777文書で、同じホストの小さ
いデーモンが配信しました。新しい形式には、代替表現ではないことを示す
指定があります。別のビルド比較では、形式を加えたときに変わったHTMLは
ゼロバイトでした。後の編集や見た目の変更を測ったものではありません。

そのテンプレートは変換内容を示します。文中リンクを文から出し、言葉は
必要な位置に残し、アドレスだけを下の独立した`=>`行へ移します。太字記
号を外し、ハイフンの箇条書きをアスタリスクへ変え、コードブロックはそ
のまま通します。Markdownの囲みとgemtextの整形済みモードの切り替え
は、同じバッククォート三つだからです。

問題が起きるところ

短い行がつながりません

文章が、節の途中で切れた短い行の不ぞろいな列になります。Markdownでよ
くするように、原稿を80桁で改行したためです。仕様は、続く短い本文行を
クライアントが長い行へ結合することを禁じます。段落ごとに一行で書く
か、変換時に同じ段落の折り返し用の改行を結合してから、ファイルへ書い
てください。

リンクがカプセルの外へ出ます

最初にたどったリンクがウェブブラウザーを開きます。変換器がすべてのリ
ンクを`https://`で始まる絶対アドレスにしたため、Geminiクライアントが
別のプログラムへ渡しました。ナビゲーションには、カプセル内で解決する
`/about/`のようなルート相対パスを使い、各ページには、ウェブ版へのリ
ンクを意図的に一つだけ置いてください。

コードが一行につぶれます

例のコードが、開始の囲み記号にくっついた長い一行になります。変換器が
コードを文章として扱い、ほかの行と結合したためです。ほかの処理より先
に囲みで文書を分割し、整形済みブロックは書いたとおりに通してくださ
い。切り替え行に置く代替テキストは、言語名などの短いものにとどめま
す。

Markdownの記号がそのまま見えます

ハイフンの箇条書き、二重のアスタリスク、下線の見出し、入れ子のリス
ト、角括弧のリンクが、そのまま表示されます。gemtextは、リスト項目に
アスタリスクと空白、見出しにハッシュ記号だけを認識し、文中のマーク
アップは一切持ちません。出力時に変換するか、初めからgemtextで書いて
ください。

文が行き先を示しません

「ここをクリック」や「上記のリンクのとおり」とだけあり、どこへ進むか
分かりません。リンクは文の外へ移り、残った言葉が行き先を示していな
かったためです。リンクのラベルに行き先を書き、文と`=>`行のそれぞれ
が、単独でも意味をなすようにしてください。

参考資料

  * gemtext記法の短い入門 — プロジェクトによる全種類の行の紹介と、
Markdownを知る人向けの説明です。

  * Geminiハイパーテキスト形式仕様 —
行の種類、構文解析の状態、折り返し規則、`lang`パラメーター、形式文法
を定める規範文書です。

  * Geminiネットワークプロトコル仕様 —
カプセルがgemtextを返す方法、リクエスト、ステータスコード、クライア
ントが従うTLSの規則です。

  * Project GeminiのFAQ — リンクが独立した行にある理由など、設計の背
景です。

hこのページのウェブ版	URL:https://engineer.company/ja/glossary/gemtext/	engineer.company	70
