Markdown完全ガイド - エンジニアの文書術

なぜMarkdownで書くのか — Wordとの本質的な違い

研修で最初に触れる文書ツールはWordかもしれない。しかし開発の現場では、README・設計メモ・議事録・障害報告まで、多くの文書がMarkdownで書かれている。理由は「手軽だから」だけではない。Markdownはプレーンテキストであるという一点に、本質的な違いがある。

プレーンテキストであることは、次の3つを意味する。

1. 差分が取れる。Wordのファイルでは「どこを直したか」を機械的に比較しにくいが、Markdownなら git diff で変更行が正確にわかる。文書の変更をコードと同じようにレビューできる。
2. gitで管理できる。「最終版_v2_修正済み(2).docx」のようなファイル名での版管理から解放される。履歴・ブランチ・Pull Requestという開発のワークフローに、文書がそのまま乗る。
3. どこでも書ける・読める。専用ソフトが不要で、エディタでもGitHub上でも表示できる。ツールが廃れてもテキストファイルは開けなくなることがない。

つまりMarkdownを学ぶことは記法の暗記ではなく、文書をコードと同じ土俵で管理する開発文化に参加することだ。

基本構文 — 書き方と表示のペアで覚える

覚える記法は少ない。まずインライン要素。左が書き方、右が実際の表示。

書き方	表示
**太字**	太字
*斜体*	斜体
~~取り消し線~~	取り消し線
`インラインコード`	インラインコード
[リンク](https://example.com)	リンク

ブロック要素は行頭の記号で決まる。

## 見出し(h2)

### 見出し(h3)

- 箇条書き
  - 半角スペース2つで1段ネスト

1. 番号付きリスト
2. 番号は変換時に自動で振り直される

![画像の代替テキスト](./image.png)

> 引用。他文書からの参照や注意書きに使う

画像の [] に書く代替テキストは、リンク切れ時やスクリーンリーダーで唯一の手がかりになる。空にせず「何の画像か」を書く。

コードブロックを使いこなす

技術文書の主役はコードブロックだ。バッククォート3つで囲み、開始行に言語名を必ず指定する。

```python
def greet(name: str) -> str:
    return f"Hello, {name}"
```

言語指定はシンタックスハイライトのスイッチで、読み手の解析コストを大きく下げる。python、typescript、bash、json、yaml、sql あたりは頻出なので綴りごと覚えたい。

変更点を示すときは diff を指定すると、行頭の - と + が削除・追加として色分けされる。「どこを直したか」を伝える説明で威力を発揮する。

```diff
- const timeout = 3000;
+ const timeout = 10000; // API応答の遅延に対応
```

インラインコードとの使い分けの基準は「文中で参照するか、独立して読ませるか」。コマンド名・ファイル名・変数名を文章の中で参照するなら npm install のようにインラインコード。実行してほしいコマンド列や複数行のコードは、コピーしやすいようにブロックにする。

見出し設計 — 文書の骨格をつくる

構文の次は設計の話。読みやすい文書は、書き始める前に見出しが決まっている。

• h1（#）は文書に1つ。h1は文書のタイトルであって章題ではない。本文の章はh2から始める（この記事も本文はh2からだ）。
• 階層を飛ばさない。h2の直下にいきなりh4を置かない。見出しレベルは文書の論理構造そのものなので、飛ばすと構造が壊れ、HTML変換後のアクセシビリティも損なわれる。
• 見出しだけで目次になるかを意識する。多くのツールは見出しから目次を自動生成する。「はじめに」「その他」のような中身のない見出しではなく、「導入手順」「エラー時の対処」のように拾い読みでも内容が伝わる名前を付ける。

本文より先に見出しを並べ、目次として成立しているか確認する。この一手間で文書の質は大きく変わる。

用途別の実践テンプレ — 何を先に書くか

文書の型は「読み手が最初に知りたいこと」から逆算する。頻出の3種で考える。

議事録 — 決定事項を先頭に

# 2026-05-15 定例MTG

## 決定事項

- リリース日を5/30に延期
- レビュー担当は佐藤さん

## TODO

- [ ] 移行手順書のドラフト作成（担当: 田中、期限: 5/20）

## 議論メモ

（経緯や発言の詳細）

議事録の読み手の大半は「何が決まったか」「自分は何をするのか」だけを知りたい。時系列の発言録を先頭に置くと、全員が結論を探して全文を読む羽目になる。決定事項→TODO→経緯の順に置く。

手順書 — 前提条件を最初に

# 開発環境構築手順

## 前提条件

- Node.js 20以上、Gitインストール済み
- リポジトリへのアクセス権限

## 手順

1. リポジトリをクローンする
2. 依存関係をインストールする

## うまくいかないとき

手順の途中で「実は権限申請が必要でした」と発覚するのが最悪のパターンだ。前提条件を最初に置けば、読み手は着手前に実行可能かどうかを判断できる。手順に番号付きリストを使うのは、「手順3で失敗した」と位置を特定して質問できるようにするためでもある。

README — 「これは何か」を冒頭3行で

# プロジェクト名

何をするものか・誰のためのものかを冒頭の数行で説明する。

## セットアップ

## 使い方

## 開発に参加するには

READMEの読み手はまず「このリポジトリは自分に関係あるか」を判断したい。冒頭で概要を伝え、次に「動かすまでの最短経路」であるセットアップを置く。詳細仕様や設計の背景は後ろでいい。

GitHub Flavored Markdown（GFM）の拡張

GitHub上のMarkdownには方言（GFM）があり、標準にない記法が使える。

タスクリストはチェックボックスとして描画され、IssueやPull Request上ではクリックで状態を切り替えられる。作業の進捗共有にそのまま使える。

- [x] 実装
- [ ] テスト追加
- [ ] ドキュメント更新

表は | と - で組む。2行目のハイフン行が必須で、: の位置で列の寄せ（左・右・中央）を指定できる。

| 項目    | 既定値 | 説明   |
| :------ | -----: | :----- |
| timeout |   3000 | ミリ秒 |

自動リンクも強力だ。URLは貼るだけでリンクになり、#123 はIssueやPull Requestへ、コミットハッシュはコミットページへ自動変換される。レビューコメントに「関連: #123」と書くだけで文脈がつながる。

アンチパターン — 読みにくいMarkdownの典型

最後に、レビューでよく指摘される書き方を挙げる。

• 強調の乱用。太字が1画面に何個もあると、どれも強調ではなくなる。読み落としてほしくない一点だけに使う。
• 深すぎる箇条書き。3段以上のネストは構造を整理できていないサイン。見出しで分割するか、文章に戻す。
• 言語指定なしのコードブロック。ハイライトが効かず、読み手が「これは何のコードか」から推測することになる。該当言語がないプレーンな出力でも text と明示する。
• 見出しの代わりの太字。太字の行は目次に出ず、リンクもできない。節を分けたいなら見出しを使う。

まとめ

Markdownの構文は半日で覚えられる。しかし「差分が取れる形式で書く」「読み手が最初に知りたいことから並べる」「見出しで骨格を示す」という文書術は、意識して使い続けないと身につかない。次にREADMEや議事録を書くときは、本文の前に見出しの並びから設計してみてほしい。