これはブックマークして後で参照できるMarkdown構文リファレンスです。見出し、強調、リンク、画像、リスト、コードブロック、テーブル、ブロック引用など、すべての要素を実際の例で説明します。機能が標準のCommonMarkの一部である場合はそのように記しており、GitHub Flavored Markdown (GFM)の拡張機能は明示的に示されているので、何が普遍的にサポートされており何がレンダラーに依存するかがわかります。

見出し

Markdownには2つの見出しスタイルがあります。ATXスタイルはハッシュ文字を使用します — h1に対して1つの # から h6に対して6つの ######まで。setextスタイルは = または - 文字のアンダーラインを使用し、h1h2にしか達しません。ATXはどこでも使うべきスタイルです — 明示的で、6レベルすべてに対応し、すべてのツールがサポートしています。よくある間違い:# の後にスペースを忘れること。厳密に言えば、#見出し はCommonMarkでは見出しではありません — スペースが必要です。

markdown
# Page Title (h1)
## Section Heading (h2)
### Subsection (h3)
#### Detail Level (h4)
##### Minor Heading (h5)
###### Smallest Heading (h6)

---

<!-- Setext style — only h1 and h2, rarely used -->
Page Title
==========

Section Heading
---------------

実際のドキュメントでは、通常 h1 を最上部に1つ(ドキュメントタイトル)、h2 を主要セクションに、h3 をそれらの中のサブセクションに使います。h3 より深く行くのは、さらなるネストのレベルよりもドキュメントの再構成が必要なサインかもしれません。

# の後にスペースを入れてください。 #見出し は多くの厳格なパーサーによってサイレントにパラグラフとして扱われます。CommonMark仕様では、# 文字と見出しテキストの間に少なくとも1つのスペースが必要です。

テキストフォーマット

太字は二重アスタリスクまたは二重アンダースコアを使います。イタリックは単一アスタリスクまたは単一アンダースコアを使います。太字イタリックはどちらかの3つを組み合わせます。取り消し線はGFM拡張で二重チルダを使います。インラインコードはバッククォートを使います。

markdown
**Bold text** or __Bold text__
*Italic text* or _Italic text_
***Bold and italic*** or ___Bold and italic___
~~Strikethrough~~ (GFM only)
`inline code`

*_ バリアントはほとんどの場合互換性がありますが、あるエッジケースで異なります:語中の強調。アスタリスクは語中で動作しますが(un*believe*able は unbelieveable としてレンダリングされます)、アンダースコアはそうではありません — CommonMarkでは語中のアンダースコアは強調マーカーではなく語の文字として扱われるため、un_believe_able はそのままレンダリングされます。これはアンダースコアが識別子に現れる技術的な文書で重要です。ルールとして:強調には * を使用し、スタイルの強い好みがある場合のみ _ を予約してください。同じ強調スパン内で *_ を混在させないでください — *text_ は正しく閉じられません。

リンクと画像

3つのリンクスタイルがあります:インラインリンク、参照リンク、自動リンク。画像はインラインリンクと同じ構文に ! プレフィックスを付けたものです。

markdown
<!-- Inline link: [text](url) or [text](url "title") -->
Read the [CommonMark spec](https://spec.commonmark.org/current/ "CommonMark Specification")
Format Markdown with the [Markdown Formatter](/markdown-formatter)

<!-- Reference link: define the URL separately — cleaner in long documents -->
Check the [GFM spec][gfm] for GitHub-specific extensions.

[gfm]: https://github.github.com/gfm/

<!-- Autolink: angle brackets make a URL or email clickable -->
<https://commonmark.org>
<[email protected]>

<!-- Image: same as inline link but with ! prefix -->
![Project screenshot](./docs/screenshot.png "Dashboard view")
![Alt text for accessibility](https://example.com/logo.png)
Markdownの画像には widthheight 属性がありません。 ![alt](url) 構文はサイズ指定のない単純な <img> タグにマッピングされます。画像のサイズを制御する必要がある場合は、生のHTMLを使う必要があります:<img src="url" alt="テキスト" width="400">。これは既知の制限です — Markdown Guideに回避策が記載されています。

リスト

順不同リストは -*、または + をバレットマーカーとして使います。順序付きリストは数字にピリオドを続けて使います。2つまたは4つのスペースをインデントしてリストをネストします。タスクリスト(GFM)はチェックなし項目に [ ]、チェック済み項目に [x] を使います。

markdown
<!-- Unordered list -->
- Install dependencies
- Configure environment variables
- Run the dev server

<!-- Ordered list -->
1. Clone the repository
2. Run `npm install`
3. Copy `.env.example` to `.env` and fill in values
4. Run `npm run dev`

<!-- Nested list (indent 2 or 4 spaces) -->
- Backend
  - Set up PostgreSQL
  - Configure connection string
- Frontend
  - Install Tailwind
  - Configure PostCSS

<!-- Task list (GFM) — great for README checklists -->
## Release Checklist

- [x] Unit tests passing
- [x] End-to-end tests passing
- [ ] Changelog updated
- [ ] Docker image tagged
- [ ] Deployment approved
よくある間違い:段落がリストの直前にあり、その間に空白行がない場合、一部のパーサーはリストを正しくレンダリングしません。迷ったらリストの前に空白行を入れてください。CommonMarkリスト仕様には正確なルールがあります — 一見シンプルに見えるものにしては驚くほど複雑です。

コード — インラインとフェンス

インラインコードは各サイドに単一のバッククォートを使います。ブロックにはトリプルバッククォート(フェンスコードブロック)を使い、オプションで開始フェンスの直後に言語識別子を指定します — これによりGitHub、VS Codeプレビュー、ほとんどの静的サイトジェネレーターでシンタックスハイライトが有効になります。インデントされたコードブロック(4スペースのインデント)も使えますが、フェンスブロックを優先してください:言語ヒントをサポートし、明示的で、周囲のコンテンツにもインデントがある場合でも機能します。

markdown
<!-- Inline code -->
Use the `fetch()` API to make HTTP requests.
Set the `Content-Type` header to `application/json`.

<!-- Fenced code block with language hint -->
```python
import json

with open("config.json") as f:
    config = json.load(f)

print(config["database"]["host"])
```

```typescript
interface ApiResponse<T> {
  data: T;
  status: number;
  message: string;
}

async function fetchUser(id: string): Promise<ApiResponse<User>> {
  const res = await fetch(`/api/users/${id}`);
  return res.json();
}
```

```bash
# Install dependencies and start the dev server
npm install
npm run dev
```

```json
{
  "name": "my-project",
  "version": "1.0.0",
  "scripts": {
    "dev": "vite",
    "build": "tsc && vite build"
  }
}
```

```yaml
name: CI
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci && npm test
```

一般的な言語識別子:pythonjs または javascriptts または typescriptbash または shjsonyamlhtmlcsssqlgorustjavaMarkdownプレビューツールを使用してMarkdownのレンダリング方法をプレビューしてください。

テーブル(GFM)

テーブルはGitHub Flavored Markdownの拡張機能です — CommonMark標準の一部ではありません。GitHub、GitLab、ほとんどの静的サイトジェネレーター、VS Codeでは機能しますが、すべてのMarkdownプロセッサーではありません。構文はパイプ文字を使って列を区切り、区切り行のダッシュでヘッダーを示します。区切り行のコロンが列の配置を制御します。

markdown
| Feature              | CommonMark | GFM       |
| -------------------- | :--------: | :-------: |
| Headings             | ✅         | ✅        |
| Bold / Italic        | ✅         | ✅        |
| Fenced code blocks   | ✅         | ✅        |
| Tables               | ❌         | ✅        |
| Task lists           | ❌         | ✅        |
| Strikethrough        | ❌         | ✅        |
| Autolinks            | ✅         | ✅ (ext.) |

列の配置は区切り行で設定します。:--- は左揃え(デフォルト)。---: は右揃え。:---: はセンター。ソースで視覚的に整列させるためにスペースで列を埋める必要はありません — それは見た目だけで、レンダリングされた出力には影響しません。各行の先頭と末尾のパイプはGFMでは技術的にはオプションですが、含める方がより明確なスタイルです。

ブロック引用

ブロック引用は各行に > を前置します。ネストされたブロック引用は >> を使います。ブロック引用内に他のMarkdown要素 — 見出し、リスト、コードブロック — を含めることができ、ドキュメントのコールアウトボックスとして便利です。

markdown
> **Note:** As of Node.js 18, the `fetch` API is available globally
> without importing anything. No more `node-fetch` dependency.

> This is a quote that spans
> multiple lines.
>
> And has a second paragraph.

> Outer quote.
>
> > Nested quote — useful for "quoting a quote" in changelogs
> > or spec discussions.

<!-- Blockquote containing a code block — useful for quoting error messages -->
> The migration failed with:
>
> ```
> ERROR: relation "users" already exists
> ```

水平線、改行、エスケープ

これら3つの機能は、ルールを知るまでバグのように見えるため人々を混乱させます。水平線、ハード改行、バックスラッシュエスケープにはすべて明確ではない特定の構文があります。

markdown
<!-- Horizontal rules: three or more of ---, ***, or ___ on their own line -->
---
***
___

<!-- All three render as <hr>. Most common style is --- -->

<!-- Hard line breaks: end a line with two trailing spaces, or use backslash -->
First line with two trailing spaces
Second line (rendered as a new line, not a new paragraph)

First line with backslash\
Second line (same result)

<!-- A single newline in Markdown source is NOT a line break — it's a space.
     Two newlines = a paragraph break. -->

<!-- Backslash escaping: put  before any Markdown character to render it literally -->
*This is not italic*
# This is not a heading
[Not a link](not-a-url)
`Not inline code`

<!-- Characters that can be escaped -->
\ ` * _ { } [ ] ( ) # + - . !
改行のための末尾スペースのトラップ:多くのエディタは保存時に末尾のスペースを削除し、ハード改行をサイレントに削除します。エディタやCIパイプラインが末尾スペースを削除する場合は、バックスラッシュ(\)アプローチの方が堅牢です。あるいは、ハード改行がより少なく済むようにコンテンツを再構成してください — それらは詩や住所でよく必要とされますが、ドキュメントではあまりありません。

MarkdownのHTML

ほとんどのMarkdownプロセッサーは生のHTMLをそのまま渡し、純粋なMarkdown構文では表現できない便利なパターンが使えます。GitHubのREADMEで最も一般的なユースケースは <details>/<summary> の折りたたみセクションです。他に便利なもの:キーボードショートカット用の <kbd>、精確なアンカーリンクのための見出しのカスタム id 属性。

html
<!-- Collapsible section — very common in GitHub READMEs -->
<details>
<summary>Click to expand: Advanced configuration options</summary>

You can override the defaults by creating a `config.local.json` file
in the project root. Supported keys:

| Key        | Default | Description             |
| ---------- | ------- | ----------------------- |
| `port`     | 3000    | Dev server port         |
| `logLevel` | `info`  | One of debug/info/warn  |

</details>

<!-- Keyboard shortcuts -->
Press <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>P</kbd> to open the command palette.

<!-- Custom heading ID for anchor links -->
<h2 id="configuration-reference">Configuration Reference</h2>

<!-- Link to that heading from anywhere -->
See the [Configuration Reference](#configuration-reference).

重要な注意点:<details> ブロックは、ボディコンテンツがMarkdownを含む場合、</summary> 閉じタグとボディコンテンツの間に空白行が必要です。空白行がないと、内部のMarkdownは解析されません — 生のテキストとしてレンダリングされます。Markdownファイルを整理してフォーマットするには Markdownフォーマッターツールを使用してください。

まとめ

これで完全な構文をカバーしました — 標準CommonMarkと開発者が日常的に使うGFM拡張。エッジケースの決定的な情報については、CommonMark仕様GFM仕様はどちらも単なるリファレンスダンプではなく、読みやすいドキュメントです。CommonMarkクイックリファレンスは便利な単一ページのサマリーです。Markdown Guideの基本構文拡張構文のページも、例とともに詳しい散文の説明が欲しい場合によく整理されています。コミット前にMarkdownがどのように見えるかを確認する必要がある場合、Markdownプレビューツールがブラウザでリアルタイムにレンダリングします。ドキュメント全体の不一致なフォーマットをクリーンアップするには、Markdownフォーマッターが見出しスタイル、リストマーカー、スペーシングを正規化します。Markdownプロセッサーが出力するHTMLをきれいにするには、HTMLフォーマッターがそれを美化します。