この記事のポイント

  • GitHub Flavored Markdown(GFM)仕様はCommonMarkの厳密な上位集合であると明記している
  • GFMの拡張には表、タスクリスト、取り消し線、拡張自動リンクが含まれる
  • Markdownは2004年にJohn Gruberらが公開したプレーンテキスト形式が起源である
目次
  1. Markdownは装飾ではなく構造
  2. まず覚えたい基本ルール
  3. CommonMarkと方言を区別する
  4. 生成AIに渡す文書の設計
01

Markdownは装飾ではなく構造

Markdownは「#」で見出し、「-」で箇条書き、バッククォートでコードを示す軽量マークアップ言語である。GFM仕様は、Markdownを「構造化された文書を書くためのプレーンテキスト形式」と定義し、電子メールやニュース投稿の書式慣習を基にしたと説明する。専用ソフトがなくても原文が読め、HTMLなど別形式へ変換しやすい点が特徴である。

生成AIにとっても、見出しやリストは内容の区切りを示す手掛かりになる。ただし記法が内容の正しさを保証するわけではない。用語、条件、責任範囲を文章として明示することが前提であり、構造はその伝達を助ける道具にとどまる。

02

まず覚えたい基本ルール

見出し記号の後には半角スペースを置き、見出しのレベルを順番に使う。段落の間には空行を入れ、箇条書きの階層ではインデントをそろえる。コードや設定値はバッククォートで本文と区別し、まとまったコードは言語名付きのフェンスで囲む。

リンクは表示文とURLを分け、画像には内容が分かる代替テキストを付ける。表は比較には便利だが、セルが長くなるとスマートフォンでは読みにくい。単純な列挙で済む内容はリストへ置き換える判断が、崩れにくさにつながる。

03

CommonMarkと方言を区別する

GFM仕様(バージョン0.29-gfm、2019年4月6日)は、GFMがCommonMark仕様に基づく「厳密な上位集合」であると明記する。CommonMarkにない機能は拡張として区別され、表、タスクリスト項目、取り消し線、拡張自動リンクがその例である。

仕様が必要になった理由もGFM仕様は詳しく述べる。原典の説明が曖昧だったため実装ごとに解釈が分かれ、あるシステムで正しく表示される文書が別のシステムでは異なる結果になる問題が起きた。利用するサービスがどの仕様と拡張を採用するかを確認し、互換性が必要な文書ほど基本構文へ絞るのが安全である。

04

生成AIに渡す文書の設計

AIへの指示では「目的」「入力」「出力形式」「禁止事項」「例」を見出しで分ける。必須条件を一つの長い段落へ埋め込まず、検証できる箇条書きにする。サンプルコードは命令文と混ぜず、言語名付きフェンスで囲む。

最終的な品質基準は、人が原文を読んで意味を確認できることである。独自記号を増やすより、短い文と具体的な見出し、参照元へのリンクを使う方が、要約や再利用の過程で情報を保ちやすい。脚注など一部のエディターでしか表示できない記法は、受け渡し先で文字列のまま残る可能性を考えて使うべきである。

出典・参考資料