この記事の要点

Markdown は John Gruber が Aaron Swartz と共に 2004 年に発表した軽量マークアップ言語 「読みやすい平文のまま記述でき、HTML に変換できる」が設計思想。元の HTML 変換は Perl スクリプト 方言が乱立したため CommonMark (2014-) で仕様策定、さらに GitHub Flavored Markdown (GFM) が事実上の標準に 見出しは #、強調は **bold**、リストは - / 1.、コードブロックは ``` で囲む GitHub / GitLab / Qiita / Zenn / note / Notion / Slack など主要プラットフォームが採用 拡張仕様: GFM テーブル、タスクリスト、脚注、絵文字、front-matter (YAML/TOML)、MyST (Sphinx 用)、Pandoc 拡張 pandoc は Markdown と Word/LaTeX/HTML/EPUB/PDF など 40 以上の形式を相互変換できる定番ツール

概要

Markdown は、John Gruber が Aaron Swartz と協力して 2004 年に発表した軽量マークアップ言語である。Gruber 自身の説明によれば「平文で書きながら HTML に変換できること、しかも変換前の状態でも十分に読めること」が設計目標であり、メールやプレーンテキストの慣習 (見出しのアンダーライン、リストのアスタリスク、強調の *word* など) を意図的に取り込んでいる。

当初は Perl 製の変換スクリプト Markdown.pl 一本だけだったが、軽さと書きやすさから爆発的に普及し、各種パーサが乱立する過程で「Markdown 方言」が大量に生まれた。それを統一すべく 2014 年に CommonMark 仕様が公開され、GitHub・GitLab・Reddit・Stack Overflow・Discord などの主要プラットフォームが採用したことで、Markdown は事実上の Web 上での「軽量原稿フォーマット」となった。GitHub の方言である GitHub Flavored Markdown (GFM) はテーブル・タスクリスト・自動リンク・取り消し線・シンタックスハイライトを公式拡張として定義しており、現在最も広く使われる方言である。

内部構造と記法

Markdown はテキストファイルそのものであり、特別な内部構造を持たない。記法のみ次に示す。

# 見出し H1
## 見出し H2
### 見出し H3

**強調 (bold)** *斜体 (italic)* ~~取り消し~~ `inline code`

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

1. 番号付き
2. 番号付き

> 引用ブロック
> 複数行

[リンクテキスト](https://example.com)
![画像 alt](https://example.com/img.png)

```python
def hello():
    print("Hello, Markdown")
```

| 列1 | 列2 |
|-----|-----|
| a   | b   |

- [x] 完了タスク
- [ ] 未完了タスク

[^1]: 脚注

多くのドキュメントでは冒頭に YAML / TOML の front-matter を置き、タイトル・作者・日付・タグなどのメタデータを与える (Jekyll、Hugo、Zola、Astro 等の静的サイトジェネレータが採用)。

---
title: "Markdown 入門"
date: 2026-06-22
tags: [markdown, docs]
draft: false
---

本文がここから始まる。

主な用途

• OSS の README: README.md は GitHub / GitLab / Bitbucket のリポジトリトップで自動レンダリング。
• 技術ブログ・Q&A サイト: Qiita / Zenn / Stack Overflow / Dev.to / Hashnode はすべて Markdown 入稿。
• 静的サイトジェネレータ: Hugo / Jekyll / Gatsby / Next.js (MDX) / Astro / VitePress の原稿フォーマット。
• ドキュメント生成: MkDocs / Docusaurus / Sphinx (MyST 経由) / GitBook で API・SDK ドキュメントを生成。
• ノート・ナレッジベース: Obsidian / Logseq / Notion / Joplin / Bear はローカル Markdown を直接編集・保存。
• 論文・書籍執筆: pandoc を使った Markdown → LaTeX → PDF / EPUB 出版。R Markdown / Quarto は学術界で定着。

関連形式との比較

形式	記述難度	表現力	標準化	主な利用先
Markdown	低	中	CommonMark / GFM	Web 原稿全般
reStructuredText	中	高 (拡張ディレクティブ)	Docutils / Sphinx	Python 公式ドキュメント
AsciiDoc	中	高	AsciiDoctor	O'Reilly 書籍、技術書典
HTML	高	最大	W3C	Web 全般
LaTeX	高	最大 (数式)	LaTeX Project	数理系論文
MyST	中	高 (Sphinx 拡張)	Executable Books	科学技術ドキュメント

編集・パーサ・ツール

# pandoc で Markdown → HTML / Word / PDF / EPUB
pandoc input.md -o output.html
pandoc input.md -o output.docx
pandoc input.md --pdf-engine=lualatex -o output.pdf
pandoc input.md -o output.epub --metadata title="My Book"

# CommonMark 準拠の C 実装 cmark
echo "# Hello" | cmark

# markdownlint で記法チェック
npx markdownlint-cli2 "**/*.md"

# MkDocs でドキュメントサイト生成
mkdocs new my-site && cd my-site && mkdocs serve

# VSCode / Obsidian でリアルタイムプレビュー
code --install-extension yzhang.markdown-all-in-one

# git diff を見やすく
git diff --word-diff README.md

注意点・落とし穴

• 方言の差異: GitHub と Qiita と Zenn でテーブルの揃え方や絵文字対応が違う。互換性を意識するなら CommonMark の機能だけに留め、拡張は明示的に宣言する。
• 生 HTML の許容: 多くの Markdown 処理系は HTML タグをそのまま通すが、CommonMark 厳格モードや GitHub のサニタイザで <script> や <iframe> が落とされる。プラットフォームごとに挙動が異なる。
• 改行の扱い: 元の Markdown 仕様では「行末スペース 2 個」で改行、CommonMark でもデフォルトはそれだが、GFM や Qiita は「改行 1 つで <br>」になる「ハードリブレイク」モードを採用しているケースがある。
• リスト内の段落: 箇条書きの中に段落・コードブロック・別のリストを入れる場合のインデント (半角 2 個 or 4 個) が処理系で揺れる。
• 表のセル内改行: パイプ | 文字を表内に書くにはエスケープ \| が必要。セル内改行は <br> を直接書くのが定番。
• front-matter の方言: Hugo は TOML (+++)、Jekyll は YAML (---)、Astro は YAML だがフィールド名が独自。プラットフォーム移行時に書き換えが要る。

関連リンク

• テキスト・ドキュメント形式 (親カテゴリ)
• ファイル拡張子とは (概論)
• PDF (.pdf) / CSV (.csv) / TXT (.txt)
• CommonMark 公式サイト
• GitHub Flavored Markdown Spec
• Pandoc — universal document converter