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は公開する形式だからです。
数行で、大半が分かります。
移行は**一晩**、手順は三つでした。
- 書き込みを止める
- `pg_dump`でデータをコピーする
- [アプリケーション](https://example.com/app/)の接続先を新しいホストにする変換器は、これを、strong要素のある段落、三項目の一覧、インラインのコード、リンクに変えます。元の文章は、誰かが入力したメモとして、そのまま読めます。

写真: Darkmoon_Art / Pixabay 
写真: iniesta44 / Pixabay
用語の背後にある前提を検証する
解説とリンク先の実績を参考に、プロジェクトについての質問を整理してください。ツールを選ぶ前に、前提を一緒に検討できます。 HTML/HTML5でWebアプリケーション100個を開発 — 100 構築したWebアプリケーション
なぜ重要なのか
ソース自体が文書であり、普通のテキストは、周りのどの道具より長く残ります。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版も、一回のリクエストで取れます。
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パラメーターです。

