Markdown

どのようなものか

Markdownは、文書を普通のテキストファイルとして書く方法です。強調する
語をアスタリスクで囲む、見出しの前にハッシュ記号を置く、箇条書きの各
項目をハイフンで始める、リンクに角括弧と丸括弧を続けるといった、少数
の書き方が、どのHTMLを作るかを変換器に伝えます。名前は、構文と、最初
に公開された変換プログラムの両方を指します。ファイルの拡張子は、通常
`.md`か`.markdown`です。CommonMarkやGitHub
Flavored Markdown（GFM）など、後から生まれた方言も、Markdownと呼びま
す。

John Gruberが2004年にAaron
Swartzと協力して開発し、最初の変換器をPerlで書きました。最終リリース
Markdown
1.0.1の日付は、2004年12月17日です。掲げた最優先の目標は、読みやすさ
でした。文書は、普通のテキストのまま公開でき、タグや書式命令でマーク
アップしたようには見えないものにすべきだと考えていました。構文に最も
大きく影響したのは、既に使われていた、プレーンテキストの電子メールの
書式だと書いています。構文にないものは、切り替えや区切り記号なしに、
文章の中にHTMLを書きます。彼の考えでは、Markdownは書く形式、HTMLは公
開する形式だからです。

数行で、大半が分かります。

```markdown
移行は**一晩**、手順は三つでした。

i- 書き込みを止める		engineer.company	70
i- `pg_dump`でデータをコピーする		engineer.company	70
i- [アプリケーション](https://example.com/app/)の接続先を新しいホストにする		engineer.company	70
```

変換器は、これを、`strong`要素のある段落、三項目の一覧、インラインの
コード、リンクに変えます。元の文章は、誰かが入力したメモとして、その
まま読めます。

なぜ重要なのか

ソース自体が文書であり、普通のテキストは、周りのどの道具より長く残り
ます。Markdownファイルは、どのエディターでも開け、版管理で行ごとの差
分を比べ、プルリクエストでも明確にレビューできます。提供元が形式を廃
止することはできず、まとまった文章を別のシステムに移すには、ファイル
をコピーするだけです。

代価は、曖昧さです。CommonMarkプロジェクトは、Gruberの説明は構文を一
意に定めず、スクリプトには不具合があり、最後の更新も2004年12月だった
ため、2014年には、何十もの実装が、それぞれ違う方法で隙間を埋めていた
と明言します。例は、GitHubのwikiと、PandocでDocBookに変換した場合と
で、別の形になる文書です。Markdownは、どの入力も構文エラーとして拒否
しないので、違いは、誰かが出力を見て初めて分かります。同プロジェクト
は、同じ入力を二十を超える実装に通し、一致するかを見るBabelmark
3を挙げます。

2014年に始まったCommonMarkは、John
MacFarlaneの仕様で応えます。規則ごとに、入力と、それが出すべき正確な
HTMLの例を結び付けます。2024年1月28日付の0.31.2には、652例あります。
GitHubは、独自の方言GFMをCommonMarkの厳密な上位集合と定義し、表、タ
スクリスト項目、取り消し線、拡張した自動リンク、少数の生HTMLタグを無
効にするフィルターを加えます。HugoのMarkdown変換器Goldmarkは、
CommonMark仕様に準拠し、GFMにも対応します。

通信上の名前もあります。2016年3月のRFC
7763は、構文の系統全体に`text/markdown`を登録しました。`charset`は必
須で、ファイルがどの方言かを表す`variant`パラメーターは任意です。

実際の活用例

このサイトで手作業で作成するページはMarkdownで、Goテンプレートが配置
を決めます。クレジットのページは、両方を静的サイト生成器Hugoと並べ、
ページを作る道具として挙げます。同じページには、ソースの正しさを保つ
リンターとしてmarkdownlintも載せています。すべての診断をエラーとする
品質ゲートの一部です。

AIエージェントに読めるサイトにするページは、形式を逆向きに使います。
ここのすべてのページには、同じアドレスにMarkdown版があり、`index.md`
を足すか、`text/markdown`を要求して取得します。ビルドは、すべての
Markdown版に不要なマークアップが残っていないかを読み、間違いがあれば
公開を拒否します。そのページのMarkdown版も、一回のリクエストで取れま
す。

```sh
curl -sL https://engineer.company/ja/ai-ready/index.md
```

約50,000語のソフトウェア文書を、GitHub、Craft、ConfluenceでMarkdown
にし、多くを人の手で執筆しました。何度も質問されていたアーキテク
チャー、手順、使い方を扱い、版管理し、見つけられる状態に保ち、新しく
入った人が早く仕事を理解できるようにしました。

問題が起きるところ

太字がアスタリスクのまま表示されます。
太字にするはずの語の両側に二つずつアスタリスクが見えても、HTMLは正し
く、リンクも動くため、検査はすべて成功します。CommonMarkは、開始側の
条件（left-flanking）を満たすアスタリスクの並びでのみ強調を開始しま
す。その並びの直後に、リンクの角括弧のような句読記号が続く場合は、並
びの直前に空白か句読記号がある場合だけです。前に文字があると、アスタ
リスクはそのまま残ります。Markdownを解析する前に、テンプレートエンジ
ンが置いたものも同じです。Hugoは、ショートコードを、英数字の仮の文字
列に置き換えます。このサイトのMarkdown版テンプレートには、ショート
コードと隣の太字の間の空白を消したことで、三言語の60項目の太字が壊れ
た記録があります。空白を保ち、ソースではなく表示したページを確認しま
す。このサイトの品質ゲートは、ビルドしたHTMLを読み、Markdownが記号の
まま読者に届いていないかを検査します。

同じファイルが、二通りに変換されます。
入れ子の一覧が、一方で平坦になり、他方では入れ子のままだったり、行頭
のハッシュ記号が、一方で見出しになり、他方では文字のままだったりしま
す。Markdownには報告すべき構文エラーがないので、何も知らせません。原
因は方言の違いで、二つの変換器が、元の曖昧な箇所を違う方法で埋めてい
ます。使う方言を明記します。多くはCommonMarkかGFMです。それに従わせ
るリンターを使い、不確かな入力は、頼る前に複数の実装に通します。

ページのMarkdown版に、HTMLが入ります。
テキスト版の読者が、生の`svg`要素や、先頭のプラス記号が数値文字参照
になった電話番号に出会います。Webページ用のHTMLを出す部品は、別の指
示がなければ、ほかのすべての形式にも同じHTMLを出します。Hugoは、出力
形式別にショートコードのテンプレートを探し、なければHTML版を使いま
す。このサイトのショートコードテンプレートは、両方の事例を記録しま
す。クレジットのMarkdown版の生の`svg`要素49個と、HTML用にエスケープ
された連絡先ページの電話番号です。今は、マークアップを出すショート
コードに、Markdown出力専用のテンプレートを用意します。品質ゲートは、
コードを除き、Markdown版に生のHTMLもHTML実体参照も含まれないことも確
認します。

生のHTMLがページから消えます。
Markdown内のHTMLブロックが、ソースは正しそうなのに、ビルドしたページ
にはありません。Gruberの構文は、文章のどこにでもHTMLを置けますが、変
換器は拒否できます。HugoのGoldmarkの`unsafe`は既定で無効なので、
Markdownに混ぜた生HTMLは表示されません。GFMは、`script`や`iframe`な
ど、少数のタグをエスケープし、文字として表示します。代わりに、Hugoな
らショートコードや描画フックなど、生成器の機能を使うか、設定を意図的
に有効にし、通すものを受け入れます。

リンターは、無視するよう指示されたものを通します。
構造の壊れたMarkdownが、markdownlintの指摘なしにレビューを通ります。
検出するはずの規則が設定で無効になり、理由も書いていません。このサイ
トの開発規則には、以前、markdownlintの設定に、コメントなしで六つの規
則を無効にしたJSONファイルを使っていたことと、六つを調べると、二つが
実際の不具合を隠していたことが記録されています。無効にする規則の横
に、コメントを書ける形式で理由を残します。次の人が、その理由に異議を
唱えられるようにするためです。

参考資料

  * CommonMark仕様 — 規則ごとに、入力と、それが出すべきHTMLの例を結
び付けた仕様です。

  * CommonMark — 仕様が必要になった理由、実装が分かれた経緯、保守す
る人々です。

  * John GruberのMarkdown — 最初の説明、設計目標、Perlスクリプトで
す。

  * Markdownの構文 — インラインHTMLの規則を含む、Gruber自身の構文説
明です。

  * GitHub Flavored Markdown仕様 —
CommonMarkの上位集合としてのGitHubの方言で、拡張をそれぞれ示します。

  * RFC 7763：text/markdownメディア型 —
メディア型、必須の`charset`、`variant`パラメーターです。

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