マークダウンの価値は変換後の見た目ではなく、テキストのまま読めることにある

見出しを大きくしたいから、行頭に # を三つ打つ。この使い方をしている文書は、画面では立派に見えて、構造としては嘘をついています。# の数は文字の大きさではなく、その行が何段目の見出しかという宣言だからです。この記事の主張は、マークダウン（Markdown）の価値は変換後の見た目ではなく、変換する前のテキストのまま読めることにあり、その一点がAIとの共通の書式になった理由でもある、ということです。成り立ち、基本の書き方、よくある誤用、限界、AIとのやりとりでの使い方を順に見ます。

設計の第一の目標は、記号のままで読めることでした

マークダウンは、技術ライターでありプログラマーでもあるJohn Gruberが2004年に発表した、軽量なマークアップ言語です。最初のバージョンはPerlのスクリプトとして作られました。Gruberは、プレーンテキストのままでも読みやすいことを、設計の最も大事な目標に置きました。HTMLに変換できることは、その次です。

だから記号は、プレーンテキストのメールで人が昔から使ってきた書き方から選ばれています。行頭の記号で箇条書きにする、記号で語を挟んで強調する、行頭に > を置いて引用する。HTMLなら h1 のタグで文字を挟む見出しも、マークダウンなら行頭に # を置くだけです。変換しなくても、読む人には構造が伝わります。

いまでは、GitHubやGitLabのREADME、Slack、NotionやObsidianのようなノートアプリ、Jupyter Notebookの説明文、JekyllやHugoなどの静的サイトジェネレーターの原稿として広く使われています。

記法は、見た目ではなく構造を宣言します

よく使う記法は次のとおりです。

要素	書き方
見出し	行頭に # を置く。数で6段階
強調	文字をアスタリスク2つずつで囲む
斜体	文字をアスタリスク1つずつで囲む
箇条書き	行頭にハイフンかアスタリスク
リンク	角括弧の文字と丸括弧のURL
引用	行頭に > を置く

# が一つならいちばん大きな見出し（H1）、二つならH2です。見出しの階層は検索エンジンが文書の構造を読み取る手がかりにもなるので、H1は文書全体の題に一度だけ使い、H2以降を各節に使うのが基本です。画像はリンクと同じ書き方の先頭に ! を付け、代替テキストには、画像が表示されないときやスクリーンリーダーが読み上げるときに内容が伝わる言葉を入れます。

見た目のために記法を使うと、構造が壊れます。目立たせたい段落を見出しにすると、目次にその段落が紛れ込みます。全部の行を強調した文書は、どこが大事かを伝えられず、どこも強調していない文書と同じ情報量になります。強調は、周りより目立つことでしか働かないからです。迷ったら、変換前のテキストを見出しの行だけ拾って読み、話の筋が通るかを確かめます。

標準がないまま広まったことが、方言を生みました

マークダウンには、長く厳密な標準規格がありませんでした。そのため実装ごとに解釈が少しずつ違い、ある画面で整う表が、隣の画面では崩れます。標準規格を持たないまま広まった記法では、崩れることが例外ではなく、ある意味で伝統になっています。この不統一を解消するため、仕様を厳密に定めるCommonMarkという取り組みが進められ、GitHub Flavored Markdown（GFM）のように、表、チェックリスト、打ち消し線などを足した拡張も広く使われています。

つまり、この記事の主張には限界があります。変換したあとの見た目が成果物そのものになる場面、たとえば高度な表や索引の要るマニュアルでは、テキストのまま読めることより、厳密に組めることのほうが重くなります。そうした文書には、文書機能の豊富なAsciiDocや、Pythonの公式ドキュメントなどで使われるreStructuredTextが選ばれることもあります。

AIとのやりとりでは、指示と出力の両方に使えます

ChatGPTなどのAIは、見出しや箇条書きを含む答えをマークダウンで返すことがよくあります。記号のままでも読め、変換すれば整うという性質が、画面に表示されるかどうか分からない場面に向いているからだと考えられます。この性質は、こちらの使い方にも生かせます。

一つは指示です。長い指示を、見出しで役割、背景、手順、出力の形式に分けて書くと、人が読み返しても、AIが読んでも、どこに何が書いてあるかが分かります。もう一つは出力です。形をこちらから決めて頼みます。

次の議事メモを、マークダウン形式で整理してください。H2の見出しを「決定事項」「保留事項」「次の行動」の三つにし、それぞれ箇条書きで3項目以内にまとめてください。

見出しの名前を先に決めて渡すのは、何を分けて考えるかという前提を渡すことでもあります。見出しの行だけを拾って読んだとき筋が通らない出力は、きれいに整形されていても、構造の上では迷子です。見出しを指定すれば、その迷子を最初から防げます。

見出しだけで、話の筋は通るか

ご自身の文書に当てはめるなら、最近書いた資料の見出しだけを並べたとき、初めて読む人に話の流れは伝わるでしょうか。AIに出力を頼むとき、見出しの名前まで自分で決めて渡しているでしょうか。

この記事の背景にある考え方は、拙著『ChatGPT 誰でも1時間でできる！ はじめてのGPTsのつくり方』の3章3節「GPTsにおける要件定義の意味と必要性」の、プロンプトに使う記号の話に書きました。GPTへの指示は、散文の長い文章で書くより、見出しと内容をひと組にした箇条書きで項目ごとに分けたほうがよい、という話で、見出し、箇条書き、番号付きリスト、区切り文字の四つを大事な記法として挙げています。そこには「人間もAIも内容を判別しやすいためです。」とあります。画面や機能は2024年時点のものですが、この節を読むと、自分の指示文を見出しの行だけ拾って読んだとき、人にもAIにも同じ筋が伝わるかどうかを、自分で確かめられるようになります。