この記事は約4分で読めます。
マークダウン記法は奥深く、楽しい — テキストだけで「伝わるドキュメント」を作る技術
はじめに
皆さんは Markdown（マークダウン） を「見出しと箇条書きが書ける記法」程度に思っていませんか？
私もかつてはそうでした。しかし、個人開発で REQUIREMENTS.md / SPECIFICATION.md / DESIGN.md などの技術ドキュメントを Markdown で書き続けるうちに、「テキストだけでここまで表現できるのか」 と驚く場面が何度もありました。
この記事では、Markdown の基本から Mermaid による図表描画、さらに Qiita 独自の拡張記法まで、「知っているだけで生産性が変わる」 テクニックを体系的に紹介します。
本記事のサンプルはすべて Qiita 上でそのまま動作します。コピー＆ペーストで試してみてください。
1. 基本記法 — 「当たり前」を正しく使えているか
テキスト装飾
**太字** は重要な箇所に。
*斜体* は英語の固有名詞や強調に。
~~打ち消し線~~ は訂正に。
`インラインコード` は関数名や変数名に。
太字 は重要な箇所に。
斜体 は英語の固有名詞や強調に。
打ち消し線 は訂正に。
インラインコード は関数名や変数名に。
Tips: 太字と斜体は組み合わせ可能です。
***太字かつ斜体***→ 太字かつ斜体
見出しの設計
# H1 — 記事タイトル（1記事に1つだけ）
## H2 — 大セクション
### H3 — サブセクション
#### H4 — 補足説明
見出しは目次の自動生成に直結します。Qiita では右サイドバーに目次が表示されるため、見出し設計 = 記事の読みやすさです。
リスト
- 箇条書き1
- 箇条書き2
- ネスト可能
1. 番号付き1
2. 番号付き2
- [ ] 未完了タスク
- [x] 完了タスク
- 未完了タスク
- 完了タスク
チェックボックスは手順書やレビューチェックリストに最適です。
2. テーブル — 比較表は Markdown の得意技
| 項目 | Markdown | HTML | Word |
|---|---|---|---|
| バージョン管理 | ◎ テキストなので diff が明確 | △ タグが冗長 | × バイナリ |
| 表示速度 | ◎ 軽量 | ○ ブラウザ依存 | △ アプリ起動必要 |
| 共同編集 | ◎ Git で管理 | ○ 可能 | △ 競合しやすい |
| 項目 | Markdown | HTML | Word |
|---|---|---|---|
| バージョン管理 | ◎ テキストなので diff が明確 | △ タグが冗長 | × バイナリ |
| 表示速度 | ◎ 軽量 | ○ ブラウザ依存 | △ アプリ起動必要 |
| 共同編集 | ◎ Git で管理 | ○ 可能 | △ 競合しやすい |
Tips: セル内の配置は
|:---|（左寄せ）、|:---:|（中央）、|---:|（右寄せ）で制御できます。
3. コードブロック — シンタックスハイライトを活用する
基本
```python
def hello():
print("Hello, Markdown!")
```
def hello():
print("Hello, Markdown!")
対応言語は多数あります: python, javascript, typescript, bash, sql, yaml, json, dart, csharp など。
diff 表示
変更前後を視覚的に示せます:
```diff_python
- def old_function():
- return None
+ def new_function():
+ return "improved"
```
- def old_function():
- return None
+ def new_function():
+ return "improved"
コードレビューや技術記事で「何が変わったか」を伝えるのに最適です。
4. 数式 — LaTeX 記法で美しい数式を
インライン数式
1日1%の成長を365日続けると $1.01^{365} \fallingdotseq 37.8$ 倍になります。
1日1%の成長を365日続けると $1.01^{365} \fallingdotseq 37.8$ 倍になります。
ブロック数式
```math
\sum_{i=1}^{n} a_i = a_1 + a_2 + \cdots + a_n
```
\sum_{i=1}^{n} a_i = a_1 + a_2 + \cdots + a_n
アルゴリズムの計算量説明や統計記事で重宝します。
5. Mermaid — テキストで図を描く
ここからが本記事の核心です。Mermaid は JavaScript ベースのダイアグラムツールで、テキストだけで 13 種類以上の図を描画できます。
Qiita では ```mermaid コードブロックで直接レンダリングされます。
なぜ Mermaid が革命的なのか
| 従来の図作成 | Mermaid |
|---|---|
| Draw.io / PowerPoint で作成 → 画像エクスポート → 記事に貼付 | テキストで書くだけ |
| 修正するたびに画像を再生成 | テキストを編集するだけ |
| Git で差分管理できない | diff で変更箇所が明確 |
| 複数人で同時編集しにくい | テキストなので Git マージ可能 |
5.1 フローチャート
最も基本的な図。処理の流れや判断分岐を表現します。
```mermaid
graph TD
A[開始] --> B{条件分岐}
B -->|Yes| C[処理A]
B -->|No| D[処理B]
C --> E[終了]
D --> E
```
-
graph TD: 上から下（Top → Down）。graph LRで左から右 -
[ ]: 四角ノード、{ }: ひし形（判断）、(( )): 円 -
-->: 矢印、-->|ラベル|: ラベル付き矢印
5.2 シーケンス図
API 通信やシステム間連携の説明に最適です。
```mermaid
sequenceDiagram
participant U as ユーザー
participant F as フロントエンド
participant A as API
participant D as DB
U->>F: ログインボタンクリック
F->>A: POST /api/login
A->>D: SELECT * FROM users
D-->>A: ユーザー情報
A-->>F: JWT トークン
F-->>U: ダッシュボード表示
```
5.3 ER 図
データベース設計のドキュメントに直接書けます。
```mermaid
erDiagram
USER ||--o{ POST : writes
USER {
int id PK
string name
string email
}
POST ||--o{ COMMENT : has
POST {
int id PK
string title
text body
int user_id FK
}
COMMENT {
int id PK
text body
int post_id FK
}
```
5.4 ガントチャート
プロジェクトのスケジュール管理を Markdown 内で表現:
```mermaid
gantt
title プロジェクトスケジュール
dateFormat YYYY-MM-DD
section 設計
要件定義 :a1, 2026-04-01, 7d
基本設計 :a2, after a1, 5d
section 開発
バックエンド :b1, after a2, 14d
フロントエンド :b2, after a2, 14d
section テスト
結合テスト :c1, after b1, 7d
```
5.5 Git グラフ
Git のブランチ戦略を視覚化:
```mermaid
gitGraph
commit id: "初回コミット"
branch feature/login
commit id: "ログイン画面実装"
commit id: "バリデーション追加"
checkout main
merge feature/login id: "PR #1 マージ"
branch feature/dashboard
commit id: "ダッシュボード実装"
checkout main
merge feature/dashboard id: "PR #2 マージ"
```
5.6 円グラフ
```mermaid
pie title 開発工数の内訳
"設計" : 15
"実装" : 45
"テスト" : 25
"ドキュメント" : 15
```
6. Qiita 独自の拡張記法
注意書き（Note）
:::note info
💡 補足情報をここに書きます。
:::
:::note warn
⚠️ 注意事項をここに書きます。
:::
:::note alert
🚨 重要な警告をここに書きます。
:::
💡 補足情報をここに書きます。
⚠️ 注意事項をここに書きます。
🚨 重要な警告をここに書きます。
アコーディオン（折りたたみ）
<details><summary>クリックで展開</summary>
長いログやコードなど、デフォルトで隠しておきたい内容を入れます。
```python
# 長いコード例
for i in range(100):
print(f"Line {i}")
クリックで展開
長いログやコードなど、デフォルトで隠しておきたい内容を入れます。
# 長いコード例
for i in range(100):
print(f"Line {i}")
脚注
Markdown は John Gruber によって作られました[^1]。
Mermaid は Knut Sveidqvist によって開発されています[^2]。
[^1]: 2004年に最初のバージョンが公開
[^2]: JavaScript ベースの OSS プロジェクト
Markdown は John Gruber によって作られました1。
Mermaid は Knut Sveidqvist によって開発されています2。
7. 実践: 私の Markdown 活用法
個人開発のドキュメントを全て Markdown で管理
私は個人開発プロダクト（3作）のドキュメントを、すべて Markdown + Mermaid で管理しています:
| ドキュメント | Mermaid の活用 |
|---|---|
| REQUIREMENTS.md | 機能一覧のテーブル |
| SPECIFICATION.md | 画面仕様のフローチャート |
| DESIGN.md | アーキテクチャのシーケンス図、ER図 |
| OPERATIONS.md | デプロイフローのガントチャート |
図を画像ファイルで管理する必要がないため、Git で完全にバージョン管理できます。 PR のレビューでも「図のどこが変わったか」が diff で確認できるのは大きなメリットです。
AI 駆動開発との相性
Claude Code などの AI ツールと Markdown は非常に相性が良いです。AI はテキストベースで思考するため、Mermaid の図も AI が直接生成・修正できます。「このシーケンス図にエラーハンドリングを追加して」と指示するだけで、テキストが更新されます。画像ベースの図では不可能な体験です。
まとめ
| レベル | 記法 | 身につくと何が変わるか |
|---|---|---|
| 入門 | 見出し / リスト / 太字 / コード | README が読みやすくなる |
| 中級 | テーブル / diff / 数式 / 脚注 | 技術記事の品質が上がる |
| 上級 | Mermaid（フロー / シーケンス / ER / ガント / Git） | ドキュメントから画像ファイルが消える |
Markdown は「テキストを装飾する記法」ではなく、「テキストだけで伝わるドキュメントを作る技術」 です。
特に Mermaid を覚えると、設計書・手順書・技術記事の表現力が飛躍的に向上します。ぜひ本記事のサンプルをコピーして、Qiita の編集画面で試してみてください。
筆者プロフィール: ソフトウェアエンジニア。「知った気にならない。いつまでも学び続ける」を信条に、業務と個人開発の両輪で技術を磨いています。AI 駆動開発で複数の個人開発アプリを構築・運用中。
👉 ポートフォリオ: 筆者ホームページ