本文へ移動
Engineer
メニュー
デザイン
日本語

Engineer / 用語集

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要素のある段落、三項目の一覧、インラインのコード、リンクに変えます。元の文章は、誰かが入力したメモとして、そのまま読めます。

なぜ重要なのか

ソース自体が文書であり、普通のテキストは、周りのどの道具より長く残ります。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ファイルを使っていたことと、六つを調べると、二つが実際の不具合を隠していたことが記録されています。無効にする規則の横に、コメントを書ける形式で理由を残します。次の人が、その理由に異議を唱えられるようにするためです。

参考資料

お問い合わせ

必要なことを整理している段階ですか?

うまくいっていないことや、つくりたいものをお聞かせください。何が必要か、おおよそいくらかかるか、私たちが適任かどうかをお伝えします。

時間単価は1,400 DKKから(VAT別)で、ご依頼期間が長いほど下がります。

welcome@engineer.company +45 50 10 61 84 デンマーク、コペンハーゲン