Markdown完全ガイド記法と表示を見比べながら学ぶ

MarkdownはGitHubのREADMEやドキュメント、メモアプリなど、さまざまな場面で使われる軽量マークアップ言語です。シンプルな記号を使うだけで、見出し・太字・表・コードブロックといった整った文書を素早く作れます。

最近注目されているClaude CodeのCLAUDE.mdもその一つで、Markdownで書くことが前提となっています。一度覚えてしまえば多くの場面で活かせる、コスパの高いスキルです。

この記事では「記法」と「表示結果」を並べて、初級・中級・上級の3段階で解説します。「どう書けばどう見えるのか」を直感的に確認しながら学んでいきましょう。

初級レベルの記法

💡 ポイント： # の数が多いほど小さい見出しになります。# の後にスペースを入れることを忘れずに。CLAUDE.mdでは文書構造を作るのに非常によく使います。

💡 ポイント： コードブロックの開始行に python や bash など言語名を指定するとシンタックスハイライトが有効になります。CLAUDE.mdでは作業手順のコマンド例などに使います。

中級レベルの記法

💡 ポイント： 区切り行（---の行）のコロン位置で列ごとに揃えを指定できます。セル幅は | を揃えなくてもOKです。

💡 ポイント： 子要素はスペース2〜4個でインデントします。CLAUDE.mdでの設定項目の階層を表現するのに便利です。

上級レベルの記法

⚠️ 注意： 上級の記法はビューワーや環境によってサポート状況が異なります。GitHub・VS Code・Obsidianなど使用するツールで確認してください。

💡 ポイント： GitHubのREADMEやCLAUDE.mdでよく使われるテクニックです。長いサンプルコードや補足説明を折りたたんですっきりさせられます。

💡 ポイント： Mermaidは flowchart（フロー）、sequenceDiagram（シーケンス）、gantt（ガント）など多種対応。GitHubやNotion、VS Code拡張で描画できます。

🤖 CLAUDE.mdでの活用例

CLAUDE.mdはClaude Codeがプロジェクトを開始する際に最初に読み込む設定ファイルです。Markdownで書くことで、AIへの指示を構造化して伝えられます。

# プロジェクト概要

このリポジトリはECサイトのバックエンドAPIです。
言語: TypeScript / Node.js
DB:   PostgreSQL

## 🚫 禁止事項

- `main` ブランチへの直接プッシュは禁止
- テストなしでの機能追加は禁止
- `any` 型の使用は原則禁止

## ✅ コーディングルール

1. 関数には必ずJSDocコメントを書く
2. エラーハンドリングは `Result` 型で統一
3. ファイル名はケバブケース（`user-service.ts`）

## 🏗 ディレクトリ構成

```
src/
├── controllers/   # ルートハンドラ
├── services/      # ビジネスロジック
└── repositories/  # DB操作
```

見出しでセクションを分け、箇条書きで禁止事項や規約をまとめ、コードブロックでディレクトリ構成を示す——これだけでClaudeはプロジェクトの文脈を正確に把握できます。

📋 Markdown早見表

レベル	記法	説明	サポート
初級	`# 〜 ####`	見出し（H1〜H4）	全環境
初級	`太字` / `斜体`	テキスト装飾	全環境
初級	`-` / `1.`	箇条書き・番号付きリスト	全環境
初級	`[text](url)`	リンク	全環境
初級	`code` / ```lang	インライン・ブロックコード	全環境
初級	`>`	引用	全環境
初級	`---`	水平線	全環境
中級	`\| col \| col \|`	テーブル	GitHub等
中級	`- [x] / - [ ]`	タスクリスト	GitHub等
中級	スペースでインデント	ネストリスト	全環境
中級	`~~テキスト~~`	打ち消し線	GitHub等
中級	\* \# \`	エスケープ	全環境
上級	`[^1]` / `[^1]: ...`	脚注	一部環境
上級	`<details>`	折りたたみ	GitHub等
上級	```mermaid	フローチャート等	GitHub・各種ツール
上級	$...$ / `$$...$$`	数式（KaTeX）	一部環境