GitHubにリポジトリを作ったとき、「README.mdってどうやって書くんだっけ？」と調べたことはないでしょうか。 あるいはZennやQiitaで技術記事を書こうとして、「見出しは#だっけ##だっけ？」と手が止まった経験もあるかもしれません。
Markdownはプログラマーが2004年に考案した軽量マークアップ言語で、プレーンテキストで書いても読みやすく、HTMLに変換すると見栄えよく表示されるという特徴を持ちます。 この記事では基本記法から拡張機能・変換の仕組みまでを体系的に解説します。
Markdownとは
Markdownは2004年にJohn Gruberが考案したテキストフォーマット記法です。 もともと「HTMLを手打ちするのは煩雑だが、プレーンテキストのままでは構造が伝わらない」という問題意識から生まれました。 「読みやすく書けるプレーンテキストのまま書いて、HTMLに変換できる」というコンセプトが、開発者コミュニティに急速に広がりました。
- 書きやすい — 特殊なソフトウェアは不要。メモ帳・VS Code・任意のテキストエディタで書ける
- 読みやすい — 変換前のプレーンテキストのまま読んでも内容が把握できる
- 汎用性が高い — GitHub・Zenn・Qiita・Slack・Notionなど多くのサービスがサポート
- バージョン管理と相性がよい — Gitで差分管理できるため、ドキュメントの変更履歴を追いやすい
現在ではGitHubのREADMEやIssue・Pull Request、技術ブログ、静的サイトジェネレーター（Next.js・Hugo・Astroなど）のコンテンツ管理に広く使われています。 エンジニアだけでなく、ライターやノンエンジニアのナレッジ管理ツールとしても普及しています。
基本記法一覧
Markdownの記法は記号の組み合わせで表現します。 以下の表に基本記法をまとめました。
| 記法 | 説明 | レンダリング結果 |
|---|---|---|
| # 見出し1 | h1タグ（最大見出し） | 見出し1 |
| ## 見出し2 | h2タグ | 見出し2 |
| ### 見出し3 | h3タグ（#を増やすほど小さく） | 見出し3 |
| **テキスト** | 太字（boldタグ） | テキスト |
| *テキスト* | 斜体（emタグ） | テキスト |
| - 項目 | 箇条書きリスト（ulタグ） | ・項目 |
| 1. 項目 | 番号付きリスト（olタグ） | 1. 項目 |
| [テキスト](URL) | リンク（aタグ） | テキスト |
|  | 画像挿入（imgタグ） | （画像が表示） |
| > 引用文 | 引用（blockquoteタグ） | 引用文 |
| --- | 水平線（hrタグ） | ─────── |
※ -の代わりに*や+でも箇条書きリストを作れます。 見出しは#から######（h6）まで対応しています。
コードブロックとインラインコード
技術文書やプログラミング関連の記事では、コードを正確に表示するための記法が重要です。 Markdownでは2種類のコード表示に対応しています。
インラインコード
文中にコードを埋め込むには、テキストをバッククォート（`）で囲みます。 例えば`npm install`と書くと、インラインコードnpm installとして表示されます。 コマンド名・変数名・ファイル名を本文中で言及するときに使います。
フェンスドコードブロック
複数行のコードを表示するには、バッククォート3つ（```）で囲むフェンスドコードブロックを使います。 開始の```の直後に言語名を指定すると、シンタックスハイライトが有効になります。
```javascript
function greet(name) {
return `Hello, ${name}!`
}
```
言語名にはjavascript・typescript・python・bash・sql・yaml・jsonなど、主要言語のほぼすべてが使えます。 言語名を省略すると装飾なしのコードブロックになります。
テーブルの書き方（GFM拡張）
テーブル（表）は標準Markdownには含まれていませんが、GFM（GitHub Flavored Markdown）の拡張機能として広く使われています。 パイプ記号（|）で列を区切り、ヘッダー行の下に区切り行（---）を入れます。
| 形式 | 特徴 | 主な用途 |
| --- | --- | --- |
| JPEG | 写真向け・非可逆圧縮 | Webの写真・SNS |
| PNG | 透過対応・可逆圧縮 | ロゴ・スクリーンショット |
| WebP | 高圧縮・透過対応 | Webの画像全般 |
区切り行の---にコロンを付けると列の揃えを指定できます。
:---— 左揃え（デフォルト）:---:— 中央揃え---:— 右揃え
GitHubやZennで使われる拡張記法
GFMやZenn・Qiita独自の拡張記法を使うと、さらに表現力が上がります。
チェックボックス（タスクリスト）
- [ ] タスク名で未完了チェックボックス、- [x] タスク名でチェック済みのリストが作れます。 GitHubのIssueやPull Requestのdescriptionで使うと、進捗が視覚的にわかりやすくなります。
打ち消し線
~~テキスト~~と書くと打ち消し線（テキスト）が表示されます。変更前の内容を残しつつ訂正を示す場面で使います。
脚注
テキスト[^1]と書き、別の行に[^1]: 注釈内容を追加すると脚注リンクが生成されます。 GitHubやZennでサポートされており、長い補足説明を本文から切り出すのに便利です。
数式（KaTeX）
ZennはKaTeXによる数式表示をサポートしています。 インライン数式は$E = mc^2$、ブロック数式は$$で囲む形式で記述します。 理工系の技術記事や数学の解説記事に役立ちます。
MarkdownがHTMLに変換される仕組み
MarkdownがHTMLになるまでには、大きく分けて「パース（解析）」と「レンダリング（出力）」の2ステップがあります。
パース: テキストをASTに変換する
Markdownパーサー（marked・remark・micromarkなど）がテキストを読み込み、AST（Abstract Syntax Tree: 抽象構文木）と呼ばれるツリー構造のデータに変換します。 ASTは「見出し要素・テキストノード・リスト要素」など文書の構造を木構造で表現したものです。
レンダリング: ASTをHTMLに変換する
ASTをHTMLに変換するレンダラーが、各ノードを対応するHTMLタグに出力します。## 見出しは<h2>見出し</h2>に、**太字**は<strong>太字</strong>になります。 この2段階設計により、ASTを使ってHTMLだけでなくPDF・LaTeX・Wordなど別の形式への変換も可能です。
ブラウザ上でMarkdownをHTMLに変換したい場合は、ぱんだツールズのMarkdown→HTML変換ツールを使うとインストール不要でその場で変換できます。
ライター・エンジニア別の活用シーン
Markdownは立場によって使い方が異なります。代表的な活用シーンをまとめます。
エンジニア向け
- README.md — リポジトリの説明・インストール手順・ライセンス情報をMarkdownで記述する
- Pull Request・Issueの本文 — 変更概要・再現手順・チェックリストをMarkdownで構造化する
- APIドキュメント — Swagger/OpenAPIのdescriptionフィールドや、Docsifyなどのドキュメントサイトで使われる
- 設計ドキュメント・ADR — アーキテクチャ決定記録（Architecture Decision Record）をMarkdownで管理し、GitHubで履歴管理する
ライター・ノンエンジニア向け
- 技術ブログ — ZennやQiitaはMarkdownで記事を書く。コードブロックや見出しを使って読みやすい記事を作れる
- 社内Wiki・ナレッジベース — Notionやesa.ioはMarkdownをサポートしており、フォーマット統一に使われる
- 日常のメモ・ノート管理 — ObsidianやLogseqなどのツールがMarkdownをネイティブ形式として採用しており、長期的な情報管理に向いている
- スライド作成 — Marpなどのツールを使うとMarkdownからプレゼンテーションスライドを生成できる
まとめ
- Markdownは2004年生まれの軽量マークアップ言語。プレーンテキストで書いてHTMLに変換できる
- 基本記法（
#で見出し、**で太字、-でリスト、[]()でリンク）を覚えれば即使える - コードブロックはバッククォート3つで囲み、言語名を指定するとシンタックスハイライトが有効になる
- テーブル・チェックボックス・打ち消し線はGFM拡張機能で、GitHubやZennなど主要サービスで利用可能
- 変換はASTを経由する2段階構造で、HTML以外の形式への出力も同じ仕組みで実現できる
- 変換を今すぐ試したい場合はMarkdown→HTML変換ツールが便利