Markdownとは：軽量マークアップ言語の基本
Markdownは2004年にJohn GruberとAaron Swartzが開発した軽量マークアップ言語です。HTMLのように複雑なタグを書かなくても、プレーンテキストに近い記法で文書構造を表現できることが最大の特長です。元々はブログ記事を効率よく書くために設計されましたが、今ではGitHub、Notion、Slack、技術ドキュメンテーションなど、あらゆる場面で標準的なフォーマットとして使われています。
Markdownが広く普及した理由は3つあります。第一に、可読性です。HTMLの<h1>タグと比べて、#一つで見出しを表現できるMarkdownはソースコード自体が読みやすいのです。第二に、ポータビリティです。プレーンテキストファイルのため、どのエディタでも開けて、バージョン管理との相性も抜群です。第三に、変換の容易さです。HTML、PDF、EPUB、Wordなど多様なフォーマットに変換するツールが豊富に存在します。
2026年現在、CommonMark仕様が事実上の標準となっています。これはGruberのオリジナル仕様の曖昧さを解消し、厳密なパース規則を定義したものです。GitHub Flavored Markdown（GFM）はCommonMarkを拡張し、テーブル、タスクリスト、取り消し線などを追加しています。どの仕様を使っているかを意識することで、レンダリング結果の差異を防げます。
本ガイドでは、CommonMarkとGFMを中心に、MDXやその他の拡張記法も含めてMarkdownの全体像を解説します。基本的な記法から始めて、複雑なドキュメント構造の構築方法まで、段階的に進めていきます。
見出し・段落・強調：テキスト構造の基本
見出しは#の数で階層を表します。# が h1、## が h2、### が h3と対応し、最大######でh6まで使えます。重要なのは#の後に必ず半角スペースを入れることです。#headerは多くのパーサーで見出しとして認識されません。また、文書構造としてh1はページに1つだけ使い、本文の構成要素にはh2以下を使うのがセマンティクス上のベストプラクティスです。
段落は空行で区切ります。連続する行は同じ段落として結合されるため、改行を明示的に入れたい場合は行末に半角スペース2つを入れるか、<br>タグを使います。ただし行末スペースは目に見えないため、多くのスタイルガイドでは避けることを推奨しています。代わりにバックスラッシュ+改行（\に続けて改行）を使う方法もCommonMarkで定義されています。
強調（emphasis）は*または_で囲みます。*italic*で斜体、**bold**で太字、***both***で斜体+太字です。GFMでは~~strikethrough~~で取り消し線も使えます。強調記法を選ぶ際のポイントは一貫性です。プロジェクト内で*と_を混在させるとコードレビュー時に混乱を招くため、どちらか一方に統一しましょう。一般的には*が推奨されます。_はスネークケースの変数名（my_variable_name）との衝突を避けられるためです。
インラインコードはバッククォート（`）で囲みます。`console.log()`のように使います。バッククォート自体をインラインコード内に表示したい場合は、二重バッククォート（`` ` ``）で囲むか、前後にスペースを入れて`` ` ``と書きます。これは意外と知られていないTIPですが、CLIコマンドのドキュメントを書く際に頻繁に必要になります。
# h1 見出し（ページタイトル）
## h2 見出し（セクション）
### h3 見出し（サブセクション）
通常の段落テキスト。
この行は上と同じ段落に結合されます。
この行は新しい段落です（上に空行があるため）。
*斜体テキスト* または _斜体テキスト_
**太字テキスト** または __太字テキスト__
***太字+斜体*** または ___太字+斜体___
~~取り消し線~~（GFM拡張）
`インラインコード` の例
``バッククォート（\`）を含むインラインコード``リスト・引用・水平線：コンテンツの整理
順序なしリストは-、*、+のいずれかで始めます。CommonMarkではどれも同じように処理されますが、一貫性のために1つのマーカーに統一するのがベストです。多くのプロジェクトでは-が標準です。ネストは4スペースまたは1タブのインデントで表現します。3段階以上のネストは読みにくくなるため、構造を見直すサインと考えましょう。
順序付きリストは数字+ピリオドで始めます。1. 2. 3.が自然ですが、実はすべて1.で書いても正しく連番がレンダリングされます。これはリストの途中に項目を挿入する際に番号を振り直す手間を省けるメリットがあります。ただし、ソースの可読性のために実際の番号を振る流派もあり、好みが分かれます。重要なのは最初の数字で、CommonMarkでは最初の数字がリストの開始番号として使われます。
引用ブロックは>で始めます。複数行に渡る引用は各行に>を付けます。>の後のスペースはオプションですが、可読性のために入れることが推奨されます。引用ブロック内に他のMarkdown要素（見出し、リスト、コードブロック）をネストすることも可能です。連続する>は同じ引用ブロックとして結合され、空の>行で段落を分けます。
水平線は---、***、___のいずれかで生成します。3つ以上の同じ文字を並べる必要があり、その行には他の文字（スペースを除く）を含めてはいけません。---は見出し（setext形式のh2）と混同される場合があるため、前後に空行を入れることを推奨します。水平線はセクションの区切りとして使いますが、HTMLのセマンティクスでは<hr>はテーマの変更を示すため、単なる見た目の区切りには過度に使わない方が良いでしょう。
- 順序なしリスト項目1
- 項目2
- ネストされた項目（4スペースインデント）
- ネストされた項目
- 項目3
1. 順序付きリスト
2. 2番目の項目
3. 3番目の項目
1. すべて1.で書いても
1. 正しく連番に
1. レンダリングされます
> 引用ブロック
> 複数行の引用
>
> 引用内の新しい段落
>
> > ネストされた引用
---
上下に空行を入れた水平線コードブロックとシンタックスハイライト
コードブロックはバッククォート3つ（```）またはチルダ3つ（~~~）で囲みます。開始行の直後に言語名を指定するとシンタックスハイライトが適用されます。対応言語はレンダラーによって異なりますが、javascript、typescript、python、go、rust、html、css、sql、bash、jsonなどは主要プラットフォームすべてでサポートされています。
コードブロック内ではMarkdown記法は無効化されます。つまり、*や#をそのまま表示できます。ただし、```自体をコードブロック内に表示したい場合はバッククォートの数を増やす（````で囲む）か、チルダで囲む必要があります。この記法はMarkdownのチュートリアルやドキュメントを書く際に不可欠です。
GFMやいくつかのプラットフォームでは、コードブロックにメタ情報を付加できます。```javascript title="example.js"のようにファイル名を指定したり、```typescript {3-5}のように行のハイライト範囲を指定できます。ただしこれは標準仕様ではなく、プラットフォーム固有の拡張です。Next.jsのrehype-pretty-codeやDocusaurusのコードブロック記法がこの例です。
インデントベースのコードブロック（4スペースまたは1タブ）もCommonMarkで有効ですが、言語指定ができないため現代では非推奨です。レガシーなMarkdownドキュメントで見かけることはありますが、新規に書く際はフェンスドコードブロック（```）を使ってください。フェンスドコードブロックは空行なしで前後のコンテンツと接することができ、文書構造をよりコンパクトに保てます。
```javascript
// 言語指定付きコードブロック
function greet(name) {
return `Hello, ${name}!`;
}
```
```python
# Pythonのコードブロック
def greet(name: str) -> str:
return f"Hello, {name}!"
```
```sql
-- SQLクエリの例
SELECT users.name, COUNT(orders.id) as order_count
FROM users
LEFT JOIN orders ON users.id = orders.user_id
GROUP BY users.name
HAVING order_count > 5;
```
// インデントベースのコードブロック（非推奨）
// 言語指定ができないリンク・画像・テーブル
リンクは[表示テキスト](URL)の形式です。[表示テキスト](URL "タイトル")でツールチップ用のタイトル属性も追加できます。参照リンクという記法もあり、[表示テキスト][ref-id]と書いて文書の別の場所で[ref-id]: URLと定義します。長いURLが多い文書では参照リンクを使うとソースの可読性が大幅に向上します。
画像はです。リンクとの違いは先頭の!のみです。画像のサイズ指定は標準Markdownには存在しません。HTMLの<img>タグを使うか、プラットフォーム固有の拡張記法を利用します。アクセシビリティのために、alt属性（代替テキスト）は必ず記述してください。スクリーンリーダーがこの情報を使用します。装飾的な画像の場合はで空のaltを指定します。
テーブルはGFM拡張の記法です。パイプ（|）とハイフン（-）で構造を表現します。2行目のセパレーター行でアライメントを指定できます。:---で左寄せ、:---:で中央、---:で右寄せです。テーブルは複雑になりがちですが、Markdownエディタの整形機能を使えばパイプを揃えた可読性の高いソースを維持できます。
テーブルの制限として、セル結合（colspan/rowspan）やネストしたテーブルはサポートされていません。複雑な表が必要な場合はHTMLテーブルを直接書くか、別のドキュメント形式を検討してください。また、テーブル内でのパイプ文字の表示には\|とエスケープする必要があります。テーブル内では改行もサポートされないため、各セルは1行で書く必要があります。
<!-- リンクの記法 -->
[Googleへ](https://www.google.com)
[タイトル付きリンク](https://example.com "サイトの説明")
[参照リンク][ref1]
[ref1]: https://example.com/long/path/to/page
<!-- 画像 -->
<!-- テーブル（GFM） -->
| 機能 | CommonMark | GFM | MDX |
| :--- | :---: | :---: | :---: |
| 見出し | ✅ | ✅ | ✅ |
| テーブル | ❌ | ✅ | ✅ |
| JSX | ❌ | ❌ | ✅ |
| 数式 | ❌ | ❌ | プラグイン |GFM拡張機能：タスクリスト、脚注、オートリンク
GitHub Flavored Markdownはタスクリスト（チェックボックス）を導入しました。- [ ]で未完了、- [x]で完了を表現します。GitHubのIssueやPRではこれがインタラクティブなチェックボックスとしてレンダリングされ、クリックで状態を変更できます。プロジェクト管理やTODOリストに非常に便利で、READMEのロードマップ表示にもよく使われます。
脚注は[^1]でマークし、文書のどこかで[^1]: 脚注の内容と定義します。学術的な文書や出典の明示が必要な場面で威力を発揮します。脚注はGFM拡張であり、すべてのMarkdownパーサーでサポートされているわけではないことに注意してください。レンダリング時にはページ末尾にまとめて表示され、クリックで移動できるリンクが自動生成されます。
オートリンクは拡張オートリンク機能により、URLやメールアドレスが自動的にリンクになります。https://example.comと書くだけで、[https://example.com](https://example.com)と同等にレンダリングされます。ただし、標準のCommonMarkではオートリンクは<URL>の形式（山括弧で囲む）のみがサポートされています。GFM拡張では山括弧なしでもURLが認識されます。
その他のGFM拡張としてアラート記法があります。> [!NOTE]、> [!WARNING]、> [!CAUTION]などで特別なスタイルの注意書きを表現できます。この記法は2023年にGitHubに導入され、技術ドキュメントの可読性を大幅に向上させました。重要な警告やヒントを視覚的に目立たせたい場合に活用してください。
<!-- タスクリスト -->
- [x] ユーザー認証の実装
- [x] APIエンドポイントの設計
- [ ] ユニットテストの追加
- [ ] ドキュメントの更新
<!-- 脚注 -->
Markdownは2004年に作られました[^1]。
[^1]: John GruberがDaring Fireballで最初に公開しました。
<!-- アラート記法（GitHub、2023年〜） -->
> [!NOTE]
> これは補足情報です。
> [!WARNING]
> この操作は取り消しできません。
> [!TIP]
> Ctrl+Shift+P でコマンドパレットを開けます。MDXとカスタム拡張：Markdownの先へ
MDXはMarkdownにJSX（Reactコンポーネント）を直接埋め込める拡張形式です。Next.js、Gatsby、Docusaurusなどモダンなドキュメントフレームワークの多くがMDXをサポートしています。技術ブログでインタラクティブなデモを記事内に配置したり、カスタムコンポーネントでコンテンツの表現力を高めたりする際に活用されています。
MDX 3.x（2024年以降の最新仕様）ではESM互換のimport/export構文が使え、型安全な開発が可能です。ただし、MDXはビルドステップが必要であり、標準のMarkdownプレビューアでは正しくレンダリングされません。チーム全体のツールチェーンが対応しているかを確認してから導入しましょう。コンテンツの移植性が下がるトレードオフがあります。
remarkとrehypeプラグインを使えば、独自の記法変換を定義できます。数式表記（KaTeX/MathJax）、Mermaidダイアグラム、シンタックスハイライトのカスタマイズ、目次の自動生成など、プラグインエコシステムは非常に充実しています。:::記法でカスタムコンテナを定義するremark-directivesは、Markdownの表現力を大幅に拡張する人気のプラグインです。
これらの拡張を使う際のアドバイスとして、標準記法で十分な部分には拡張を使わないことを推奨します。過度にカスタマイズされたMarkdownはツール間の移植性が失われ、新しいチームメンバーの学習コストも上がります。まずCommonMark+GFMで書き、本当に必要な場合にのみ拡張を導入する段階的アプローチが賢明です。
{/* MDXの例：Reactコンポーネントの埋め込み */}
import { CodePlayground } from '../components/CodePlayground'
import { Alert } from '../components/Alert'
# APIリファレンス
以下のプレイグラウンドでAPIを試せます：
<CodePlayground
language="javascript"
defaultCode="fetch('/api/users').then(r => r.json())"
/>
<Alert type="warning">
本番環境では必ず認証トークンを含めてください。
</Alert>
{/* 数式記法（KaTeXプラグイン使用時） */}
二次方程式の解の公式：
$$
x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}
$$ベストプラクティスとよくある間違い
リンターの導入を推奨します。markdownlint（VS Code拡張としても利用可能）はMarkdownの一般的な問題を検出します。例えば、見出しレベルの飛び越し（h2の次にh4）、リスト前の空行不足、行末の不要な空白などです。CI/CDパイプラインにmarkdownlint-cliを組み込めば、チーム全体で一貫した品質を保てます。
ファイル名とリンクの規則として、ファイル名はkebab-case（ハイフン区切りの小文字）が推奨です。スペースや日本語のファイル名はURLエンコードの問題を引き起こすことがあります。相対リンクを使う場合は、ファイルの移動時にリンク切れが発生しやすいため、リンクチェッカー（markdown-link-check等）を定期的に実行してください。
よくある間違いとして、コードブロックの言語指定忘れがあります。言語を指定しないとシンタックスハイライトが適用されず、読者にとって非常に読みにくくなります。もう一つはリストのインデント不統一です。2スペースと4スペースを混在させると、異なるパーサーで異なるネスト構造に解釈される可能性があります。
最後に、巨大な単一Markdownファイルは避けましょう。READMEが1000行を超えたら分割のサインです。目次（TOC）の自動生成ツールを使い、関連するセクションを別ファイルに切り出して相互リンクする構造が理想です。ドキュメントサイトジェネレーター（Docusaurus、VitePress等）を使えば、複数のMarkdownファイルをナビゲーション付きのサイトとして構築できます。