Markdown

Markdown とは

Markdown は、John Gruber が 2004 年に開発した軽量マークアップ言語で、プレーンテキストで記述した文書を HTML に変換できる。構文の設計には Aaron Swartz の助言が入っており、Gruber 自身が原典ページの謝辞に記している。GitHub の README、技術ブログ、ドキュメントサイト、チャットツール (Slack, Discord) で広く使われている。

記法がシンプルで、特別なエディタなしにテキストエディタで読み書きできる。HTML を直接書くより圧倒的に速く、プレーンテキストの状態でも読みやすい。

主要な記法

主要な記法の例を示す。

# 見出し 1
## 見出し 2
### 見出し 3

**太字** *斜体* ~~取り消し線~~ `インラインコード`

- 箇条書き
- 箇条書き
  - ネスト

1. 番号付きリスト
2. 番号付きリスト

[リンクテキスト](https://example.com)
![画像の代替テキスト](image.png)

> 引用ブロック

| 列 1 | 列 2 | 列 3 |
|------|------|------|
| A    | B    | C    |

このうち取り消し線とテーブルは、Gruber のオリジナル仕様には無い後発の拡張である。GitHub や主要なドキュメントツールでは問題なく使えるが、素の Markdown しか解釈しない変換器では記号がそのまま表示される。書く前に、変換側がどの方言を実装しているかを確かめておく。

Markdown の方言

オリジナルの Markdown は仕様が曖昧で、実装ごとに挙動が異なる問題があった。しかも公式実装の配布物は 1.0.1 (2004 年 12 月) から動いておらず、2026 年 8 月時点でもそのままである。曖昧さを詰める作業は、後から現れた仕様が引き受けた。

方言	特徴	使われる場所
CommonMark	曖昧さを排除した厳密な仕様 (John MacFarlane らが策定)	多くのパーサーの基盤
GFM (GitHub Flavored)	CommonMark を土台に、テーブル・タスクリスト・取り消し線・自動リンクを拡張として追加	GitHub
MDX	JSX コンポーネントを埋め込み可能	Next.js、Docusaurus

この 3 つは競合する規格ではなく積み重ねの関係にある。GFM の仕様書は自らを CommonMark の厳密な上位互換と位置づけており、CommonMark として正しい文書はそのまま GFM でも通る。逆は成り立たない。テーブルや取り消し線は GFM 側の拡張なので、CommonMark だけを実装したパーサーに食わせると崩れる。

MDX: Markdown + React

MDX は Markdown 内に React コンポーネントを埋め込める拡張で、Next.js や Docusaurus などの技術ドキュメントサイトで広く使われている。

静的サイトジェネレーターとの連携

Markdown は静的サイトジェネレーター (Next.js, Astro, Hugo, Gatsby) のコンテンツソースとして使われる。YAML frontmatter でメタデータを記述し、本文を Markdown で書く。

---
title: "記事タイトル"
publishedDate: "2025-06-01"
tags: ["JavaScript", "TypeScript"]
---

## 本文

ここから記事の本文が始まる。

Markdown が適さないケース

• 複雑なレイアウト (多段組み、フロート) → HTML/CSS
• 構造化データ → JSON, YAML
• リッチなインタラクション → MDX or カスタムコンポーネント
• 印刷用の文書 → LaTeX, Word

さらに掘り下げるなら関連書籍が参考になる。