概要
Markdown は、見出し・リスト・リンク・コードブロックなどを軽い記法で書ける文書形式です。このチートシートでは、README、Issue、記事、メモでよく使う基本記法と、環境によって表示差が出やすい拡張構文を整理します。
最初に覚える最小セット
| 記法 | 用途 |
|---|---|
# / ## / ### | 見出し |
- / 1. | 箇条書き |
[text](url) | リンク |
`code` | インラインコード |
| フェンス付きコードブロック | コードブロック |
> 引用 | 引用 |
| 列 | 列 | | テーブル |
Markdown は表示する場所によって対応記法が違います。README では GitHub Flavored Markdown、汎用文書では CommonMark を基準にし、独自拡張を使う前に表示環境を確認します。
見出し
| 記法 | 説明 |
|---|---|
# 見出し1 | 最大の見出し（H1） |
## 見出し2 | セクション見出し（H2） |
### 見出し3 | サブセクション（H3） |
#### 見出し4 | 小見出し（H4） |
##### 見出し5 | より小さい見出し（H5） |
###### 見出し6 | 最小の見出し（H6） |
テキスト装飾
| 記法 | 説明 |
|---|---|
**太字** | 太字テキスト |
*斜体* | 斜体テキスト |
***太字斜体*** | 太字かつ斜体 |
~~取り消し線~~ | 取り消し線 |
`インラインコード` | インラインコード |
<sup>上付き</sup> | 上付き文字 |
<sub>下付き</sub> | 下付き文字 |
ポイント: 見出しはH1からH6まで。ドキュメントの構造を明確にするため、見出しレベルを飛ばさない（H2の次にH4など）ようにしましょう。
リスト
| 記法 | 説明 |
|---|---|
- 項目 | 順序なしリスト |
* 項目 | 順序なしリスト（代替） |
1. 項目 | 順序付きリスト |
- 子項目 | ネストしたリスト（2スペース） |
- [ ] タスク | チェックボックス（未完了） |
- [x] タスク | チェックボックス（完了） |
リンクと画像
| 記法 | 説明 |
|---|---|
[テキスト](URL) | ハイパーリンク |
[テキスト](URL "タイトル") | タイトル付きリンク |
<URL> | 自動リンク |
 | 画像 |
 | タイトル付き画像 |
[参照][id] → [id]: URL | 参照リンク |
実践メモ: 参照リンク（[テキスト][id]）を使うと、URLを文末にまとめて管理でき、本文の可読性が大幅に向上します。
コードブロック
| 記法 | 説明 |
|---|---|
``` | コードブロック開始/終了 |
```javascript | 言語指定のコードブロック |
```python | Python用コードブロック |
```bash | シェルコマンド用 |
コード | 4スペースインデントでもコード化 |
ポイント: コードブロックには言語名（javascript、python等）を指定しましょう。シンタックスハイライトが有効になり読みやすくなります。
テーブル
| 記法 | 説明 |
|---|---|
| 列1 | 列2 | | テーブル行 |
|---|---| | ヘッダー区切り |
|:---| | 左寄せ |
|:---:| | 中央寄せ |
|---:| | 右寄せ |
引用とセパレーター
| 記法 | 説明 |
|---|---|
> 引用テキスト | 引用ブロック |
>> ネスト引用 | ネストした引用 |
--- | 水平線 |
*** | 水平線（代替） |
___ | 水平線（代替） |
注意: テーブルのヘッダー区切り行（|---|---|）は必須です。これがないとテーブルとして認識されません。
実践メモ: - [ ] タスクでチェックリストが作成可能。GitHubのIssueやPRで進捗管理に便利です。
拡張構文（GitHub Flavored Markdown）
| 記法 | 説明 |
|---|---|
@username | ユーザーメンション |
#123 | Issue/PRへの参照 |
:emoji: | 絵文字（例: :smile:） |
[^1] → [^1]: 注釈 | 脚注の詳細形式 |
> [!NOTE] | GitHub のアラート記法 |
<mark>重要</mark> | HTML を許可する環境でのハイライト |
注意: GFM（GitHub Flavored Markdown）の拡張機能は、他のMarkdownパーサーでは動作しない場合があります。CommonMark仕様をベースにしつつ、環境固有の拡張を確認しましょう。
エスケープ
| 記法 | 説明 |
|---|---|
\* | アスタリスクをエスケープ |
\# | ハッシュをエスケープ |
\[ | 角括弧をエスケープ |
\\ | バックスラッシュ自体 |
まとめ
Markdown は、見出し階層、リスト、リンク、コードブロック、テーブルを正しく書ければ多くの文書に対応できます。コードブロックには言語名を付け、見出しレベルは飛ばさず、リンクや画像には読み手に意味が伝わるテキストを付けます。
GFM や HTML 併用のような拡張は便利ですが、表示環境によって動作が変わります。公開前に実際の表示で確認してください。
参考リソース
- CommonMark Specification - Markdown 標準仕様
- GitHub Flavored Markdown Spec - GFM 公式仕様
- Daring Fireball: Markdown Syntax - John Gruber によるオリジナル仕様
- GitHub: Basic writing and formatting syntax - GitHub 公式ガイド
