開発・エージェント

Markdownとは

この記事の結論

Markdownとは、見出しや箇条書き、リンクなどを「#」「-」のような簡単な記号で書き表す、軽量な文書の記法です。
記号のままでも読める文書を目指して作られ、変換するとHTMLになります。書き方の揺れが多かったため、共通の仕様として CommonMark が整えられています。
AI開発では、README や仕様書、エージェントへの指示ファイル、AIの回答そのものまで Markdown で書かれることがよくあります。

まーくだうん

見出しや箇条書き、リンクなどを「#」「-」のような簡単な記号で書き表す、軽量な文書の記法です。

最終更新: 2026-09-26

Markdownとは（意味と読み方）

Markdownとは、見出しや箇条書き、リンクなどを「#」「-」のような簡単な記号で書き表す、軽量な文書の記法です。読み方は「まーくだうん」です。

作者は John Gruber で、作者による Markdown の説明（Daring Fireball）では、Web で文章を書く人のためのテキストからHTMLへの変換ツールとして紹介されています。目標に置かれたのは読みやすさで、タグや書式の指示で飾られたように見えず、そのままでも公開できる文書にすることです。

手書きのメモで見出しの前に記号を付けたり、箇条書きの頭に線を引いたりする感覚に近いので、覚える記号は多くありません。

Markdownの基本の書き方

Markdownの基本の記号
書きたいもの	書き方	補足
見出し	`# 大見出し` `## 中見出し`	`#` の数（1〜6個）で階層を表す
箇条書き	`- 項目`	番号付きは `1. 項目`
太字	`強調`	記号で文字を挟む
リンク	`[表示する文字](URL)`	角かっこの中が見える部分
コード	`npm install`	複数行は ``` で上下を囲む
引用	`> 引用文`	行頭に置く

段落どうしは空行で区切ります。ここでつまずく人が多いのが改行で、1回改行しただけでは同じ段落の続きとして扱われます。基本的な書き方とフォーマットの構文（GitHub Docs）にあるとおり、表示のうえでも行を変えたいときは、行末に半角スペースを2つ置くか、バックスラッシュを置きます。

CommonMarkとGFMの違い

Markdown には、書き方の細かい部分が決まっていないという弱点がありました。CommonMark の仕様書の前書きによると、元の説明には入れ子の箇条書きの字下げや、引用の前に空行が要るかといった曖昧な点が残り、実装ごとに結果が分かれました。同じ文書でも、表示する場所によって見た目が変わっていたのです。

CommonMark は、この曖昧さをなくすために細部まで定めた仕様です。2024年1月28日付の 0.31.2 が最新版として公開されています。

GitHub で使われているのは、GitHub Flavored Markdown（GFM）という方言です。CommonMark を丸ごと含んだうえで、表、チェックボックス付きの項目（- [ ]）、取り消し線、URLの自動リンクなどを足しています。

AI開発でのMarkdownの使われ方

README と仕様書：リポジトリの入口に置く README.md、要件定義や受け入れ基準をまとめた文書は、Markdown で書くのが一般的です。
エージェントへの指示ファイル：AIコーディングエージェントの多くは、作業の決まりごとを書いた .md ファイルをプロジェクトに置いて読ませる仕組みを持っています。
AIの回答：チャット型のAIは、見出しや箇条書きを Markdown の記号で出力することがよくあります。表示に対応していない場所へ貼ると、** などの記号がそのまま残ります。

仕様書を書くなら、筆者はワープロの文書より Markdown をすすめます。ただの文字なので Git で差分が読め、どこを変えたかを履歴で追えます。そのままAIに渡せる点も、AIと一緒に開発するうえで効いてきます。

Markdownについてのよくある誤解

誤解：Markdown は1種類 → 実際：方言がいくつもあります。表やチェックボックスは GFM の拡張なので、表示する道具によっては使えません。
誤解：改行すればそのまま改行される → 実際：1回の改行は同じ段落として扱われます。段落を分けるなら空行、行だけ変えるなら行末の空白2つかバックスラッシュを使います。
誤解：HTMLで書けることは何でも書ける → 実際：表せる書式は限られます。HTMLを直接混ぜられる場合もありますが、GFM では一部のタグが無効にされます。

出典・参考資料

Markdownについてよくある質問

Q1. Markdownとは何ですか？
見出しや箇条書き、リンクなどを「#」「-」のような簡単な記号で書き表す、軽量な文書の記法です。記号のままでも読みやすく、変換するとHTMLとして表示できます。

Q2. Markdownで改行が反映されないのはなぜですか？
1回改行しただけでは、同じ段落の続きとして扱われるためです。段落を分けるなら空行を1行入れます。段落はそのままで行だけ変えたい場合は、行末に半角スペースを2つ置くか、バックスラッシュを置きます。

Q3. CommonMarkとGFMは何が違いますか？
CommonMark は、Markdown の曖昧だった部分を細かく定めた共通の仕様です。GFM は GitHub で使われている方言で、CommonMark をすべて含んだうえに、表やチェックボックス付きの項目、取り消し線などを足しています。

Q4. Markdownを書くのに専用のソフトは要りますか？
要りません。ただの文字なので、普段のテキストエディタで書けます。仕上がりを見ながら書きたい場合は、プレビュー表示に対応したエディタを使うと、記号の付け忘れに気づきやすくなります。