Skip to content

Markdown チートシート

整形されたテキストのための軽量マークアップ言語。

01

はじめに

見出しと段落

見出しには # を使いましょう(1〜6 レベル)。代替の構文は、H1 に ===、H2 に --- です。段落の間には空行が必要です。Markdown は、プレーンテキストとして読めるように設計されています。

markdown
# Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6

Alternative Heading 1
=====================

Alternative Heading 2
---------------------

This is a paragraph. Just write
plain text. Leave a blank line
between paragraphs.

改行

行末の 2 つのスペースかバックスラッシュがハードな改行(<br>)を作ります。なければ、単一の改行は 1 段落に結合されるソフトな折り返しです。段落を分けるには必ず空行を残しましょう。

markdown
First line  
Second line (two trailing spaces above)

Or use a backslash at end of line\
to force a line break.

Soft wrap without break:
just continue on the next line
and it joins into one.

コメント

Markdown には公式のコメント構文がありませんが、HTML のコメント(<!-- -->)がほとんどのレンダラで機能し、出力では隠れます。[//]: # のトリックが、空のリンク参照を使ってメモを加えます。コメントは生のソースでは依然見えます。

markdown
<!-- HTML comments work in most Markdown -->

[//]: # (This is a comment)

[//]: # "Another comment style"

<!-- 
  Multi-line comment
  not rendered in output
-->

空白とインデント

行頭の 4 スペースがテキストをコードブロックに変えます — 意図しないインデントに注意しましょう。ネストしたリストではインデントが効きます(レベルごとに 2〜4 スペース)。タブは通常 4 スペースとして扱われます。パーサ間の描画問題を避けるため、スペースを一貫して使いましょう。

markdown
Paragraph one.

    This is an indented code block
    because of 4 spaces.

> Quoted text needs > prefix.

   Three spaces is just text
   (less than 4).

水平罫線

3 つ以上のハイフン、アスタリスク、アンダースコアが水平罫線(<hr>)を作ります。ハイフンが最も一般的です。文字の間のスペースは許されます。明快さのため、水平罫線の前後に空行を置きましょう。---(罫線)を #(見出し)と混同しないよう注意してください。

markdown
---

***

___

   * * *

Text above

---

Text below
02

テキストの整形

太字と Strong

二重のアスタリスクかアンダースコアが太字(<strong>)を作ります。アンダースコアは単語の途中では機能しないため(snake_case)、アスタリスクが推奨です。太字の中に他の強調をネストできます。フォールバックとして HTML の <strong> タグも機能します。

markdown
**bold text**
__also bold__

**bold with *italic* inside**

<strong>HTML bold also works</strong>

**bold**

斜体と Emphasis

単一のアスタリスクかアンダースコアが斜体(<em>)を作ります。アスタリスクは単語の途中でも機能し、アンダースコアは語内のアンダースコアをリテラルとして扱います(そのため no_italic_here)。フォールバックには <em> を使いましょう。斜体はスタイリングだけでなく強調のためのものです。

markdown
*italic text*
_also italic_

*italic*

<em>HTML italic</em>

normal *italic* normal

太字 + 斜体の組み合わせ

三重のアスタリスク/アンダースコアが太字と斜体の両方を作ります。ネストもできます:太字の中に斜体、またはその逆。描画では順序は問題になりませんが、読みやすさのため一貫させるべきです。

markdown
***bold and italic***
___also both___

**_bold and italic_**
*__bold and italic__*

combine **bold** and *italic*

打ち消し線

二重のチルダ(~~)が打ち消し線を作ります。GitHub Flavored Markdown の一部で、今では広くサポートされています。HTML の <del> と <s> タグが等価のフォールバックです。標準(元の)Markdown には打ち消し線が含まれていません。

markdown
~~strikethrough~~

~~crossed out text~~

<del>HTML delete</del>
<s>HTML strikethrough</s>

~~done~~ and ~~pending~~

Mark / ハイライト

ハイライトのための二重イコール(==)は、一部のパーサがサポートする拡張です(GFM コアにはありません)。HTML の <mark> タグが普遍的に機能します。キーとなる用語への注意を引くため、ハイライトは控えめに使いましょう — 乱用は効果を減らします。

markdown
==highlighted text==

<mark>HTML mark</mark>

This is ==important== text.

Compare **bold**, *italic*, ==mark==.

下付きと上付き

チルダ(下付き)とキャレット(上付き)の構文(~ ~ と ^ ^)は拡張であり、標準の Markdown にも GFM にもありません — Pandoc、R Markdown、その他少数がサポートします。普遍的な対応には、HTML の <sub> と <sup> か Unicode 文字を使いましょう。

markdown
H~2~O is water

E = mc^2^

x^2^ + y^2^ = r^2^

1st^st^ January

CO~2~ emissions
03

リスト

順序なしリスト

順序なしリストの項目には -、*、+ を使えます — 1 つ選び、一貫させましょう(- が最も一般的です)。ネストした項目には 2〜4 スペースのインデントを付けます。同じリストでのマーカーの混在は、一部のパーサで問題を引き起こし得ます。1 行 1 項目です。

markdown
- item one
- item two
- item three

* asterisk works too
+ plus sign also works

  - sub-item (indent 2 spaces)
  - another sub-item

順序付きリスト

順序付きリストは、数字にピリオドを続けます。実際の数字は連続である必要がありません — Markdown が番号を振り直します。特定の数字から始めるには、その数字を最初に使います(10. は 10 から始まります)。自動番号付けには、すべての項目に 1. を使います。

markdown
1. first
2. second
3. third

1. auto-numbered
1. still increments
1. third item

10. starts at 10
11. next

ネストしたリスト

ネストしたリストの項目は 2〜4 スペースでインデントします(混在タイプには 4 が最も安全です)。異なるレベルで順序付きと順序なしのリストを混ぜられます。深いネスト(3 レベル以上)は読みやすさを損なうため — 再構成を検討しましょう。インデントは一貫させましょう。

markdown
1. top level
   - nested unordered
   - second nested
2. back to top
   1. nested ordered
   2. another
3. third top

- fruits
  - apple
    - granny smith
  - banana

タスクリスト

タスクリストの構文(- [x] と - [ ])は GitHub Flavored Markdown の拡張です。チェックボックスは GitHub/GitLab でインタラクティブに描画されます。順序付きと順序なしのリストの両方で機能します。README、issue トラッカー、進捗管理に最適です。

markdown
- [x] completed task
- [ ] incomplete task
- [ ] another todo

1. [x] done
2. [ ] not done

- [x] Write the docs
- [ ] Review PR
- [ ] Deploy

Loose と Tight リスト

リストの項目が空行で分かれていれば、リストは「loose」です(各項目が <p> で包まれる)。空行がなければ「tight」です(<p> のラッパーなし)。これが HTML 出力の間隔に影響します。段落のラップを制御するため、空行は意図的に加えましょう。

markdown
- tight item
- tight item
- tight item

- loose item

- loose item

- loose item

複数段落を含むリスト

リスト項目に複数の段落やブロック要素を含めるには、継続行を 4 スペースでインデントします(またはリストマーカーの内容に揃える)。サブブロックは空行で分けます。複雑なリスト構造には不可欠ですが、間違いやすい部分です。

markdown
- First item

  Second paragraph of first item.

- Second item

  > A blockquote inside a list item.
  >
  > Must be indented to align.

- Third item
05

画像

基本の画像

画像の構文はリンクのようですが、! が接頭辞です。アクセシビリティのため alt テキストは必須です — スクリーンリーダーのために画像を説明し、画像の読み込みに失敗したとき表示されます。パスは相対、絶対、URL のいずれかです。タイトルは省略可能です。

markdown
![alt text](image.png)

![alt text](https://example.com/img.png)

![alt text](/path/to/image.png "Optional title")

Alt テキスト付きの画像

alt テキストは意味があり簡潔であるべきです — 「画像」ではなく、画像の目的を記述しましょう。装飾的な画像には、スクリーンリーダーにスキップさせるため、空の alt(alt='')が受け入れられます。「image of」や「picture of」は決して使わないでください — スクリーンリーダーが既に告知します。

markdown
![A diagram showing the system architecture](architecture.png)

![Photo: mountain landscape at sunset](mountains.jpg "Sunset over the Alps")

![](decorative-icon.png)

リンク付き画像

リンクの構文の中に画像の構文をネストすれば、画像をリンクで包めます:[![alt](img)](url)。フルサイズへのリンクを持つサムネイル、CI のステータスへのリンクを持つバッジ、ホームへのリンクを持つロゴでよくあります。画像だけでなく宛先を記述する alt テキストを保ちましょう。

markdown
[![alt text](thumbnail.png)](https://example.com/full)

[![logo](logo.png "Visit home")](/)

[![badge](https://img.shields.io/build.svg)](https://ci.example.com)

参照画像

参照画像は、リンクと同じ参照スタイルを ! 接頭辞付きで使います。画像の参照は一度定義し、再利用しましょう。同じ画像が複数回現れるときや、画像の多い段落を読みやすく保つときに有用です。

markdown
![alt text][img-ref]

[img-ref]: https://example.com/image.png "Title"

![alt][logo]

[logo]: /assets/logo.png

画像の寸法と Figure

標準の Markdown には画像のサイズ指定の構文がありません — width/height 属性付きの HTML の <img> を使いましょう。パーセンテージの幅でレスポンシブなサイズ指定が可能になります。セマンティックなキャプション(HTML5)を提供するのが、<figure> + <figcaption> の組み合わせです。一部の拡張 Markdown(Pandoc)は ![alt](img){width=300} に対応しています。

markdown
<img src="image.png" width="300" height="200" alt="sized image">

<img src="banner.png" width="100%" alt="responsive">

<figure>
  <img src="diagram.png" alt="flowchart">
  <figcaption>Figure 1: System flow</figcaption>
</figure>
06

インラインコードとエスケープ

インラインコード

インラインコードは単一のバッククォートで包みましょう。コードの中にバッククォートを示すには、区切りとして(またはそれ以上の)二重のバッククォートを使います。インラインコードは等幅で描画され、Markdown としてパースされません。ファイル名、コマンド、コードの識別子に最適です。

markdown
Use the `printf()` function.

Inline code: `const x = 42;`

Code with backticks: ``use `code` here``

A `<div>` element.

コードスパンでのバッククォートのエスケープ

コードスパンの中にバッククォートを含めるには、内側に現れるものより多いバッククォートを区切りとして使います:単一のバッククォートの周りに二重のバッククォート。コードスパンの外では、バッククォートはバックスラッシュでエスケープしましょう。閉じる fence は開く長さと一致しなければなりません。

markdown
To show a backtick inside code,
use more backticks as delimiters:

`` ` ``        one backtick
`` a`b ``      backtick inside text

Use \ to escape outside code:
A literal backtick: \`

コードスパンと空白

コードスパンは内部の空白を正確に保持します。よくあるトリック:通常なら切り詰められる前後のスペースを表示するため、内容を前後に単一のスペースで包みます。両側の 1 スペースは自動的に剥ぎ取られます。

markdown
`  spaced  `  (spaces preserved)

` code ` with one space pad

`function f() { return; }`

`  multi   word   code  `

バックスラッシュエスケープ

バックスラッシュが特殊な Markdown 文字をエスケープします:バッククォート、アスタリスク、アンダースコア、波括弧、角括弧、丸括弧、ハッシュ、プラス、マイナス、ドット、感嘆符、バックスラッシュ自体です。エスケープすると文字がリテラルとして描画されます。フォーマットとして解釈される文字だけをエスケープしましょう。

markdown
\*not italic\*
\_not italic\_
\#not a heading
\[not a link](url)
\`not code\`
\\backslash itself
\!not an image

エスケープすべき文字

これが Markdown でエスケープ可能な文字です。すべてがどこでもエスケープを要するわけではありません — # は行頭でのみ効き、- はリストの文脈で、など。迷ったらエスケープしましょう。波括弧と丸括弧は、通常特定の文脈(リンク、テンプレート文字列)でだけエスケープが必要です。

markdown
\\     backslash
\`     backtick
\*     asterisk
\_     underscore
\{ \}  curly braces
\[ \]  square brackets
\( \)  parentheses
\#     hash
\+     plus
\-     minus
\.     dot
\!     exclamation
07

コードブロック

インデントされたコードブロック

4 スペース(かタブ)のインデントがコードブロックを作ります。インデントされたコードブロックには構文ハイライトと言語タグがなく、リスト項目の中では使えません(継続として扱われます)。新しいコンテンツには fenced コードブロックを推奨します — インデントされたブロックはレガシーです。

markdown
Normal paragraph.

    // indented code (4 spaces)
    function hello() {
      console.log("hi");
    }

Back to normal text.

Fenced コードブロック

三重のバッククォートか三重のチルダが fenced コードブロックを作ります。fence がインデントされたブロックより推奨です — 曖昧さがなく言語のヒントをサポートします。コード自体が三重のバッククォートを含むとき、チルダ(~~~)が有用です。fence は同じ文字数で必ず閉じましょう。

markdown
```
plain code block
multiple lines
```

~~~
also a fenced block
using tildes
~~~

構文ハイライト

構文ハイライトのため、開く fence の直後に言語識別子を加えましょう(js、python など)。ほとんどのレンダラが highlight.js か Prism を使います。よくある別名:js、ts、py、rb、sh、json、html、css。言語が未知なら、素の等幅のため省きましょう。

markdown
```javascript
const greet = (name) => {
  console.log(`Hello, ${name}!`);
};
```

```python
def greet(name):
    print(f"Hello, {name}!")
```

```bash
echo "Hello, $USER"
```

ネストしたコード fence

コードブロックの中にバッククォートを表示するには、別の fence を使いましょう(バッククォートの内容にはチルダ、または内側に現れるものより多いバッククォート)。三重のバッククォートを含む内容は、4 つのバッククォートで fence します。閉じる fence は開く長さと一致しなければなりません。

markdown
Use four backticks to wrap triple backticks:

````
```js
console.log("inside");
```
````

Or use tildes to wrap backtick content:

~~~
```js
code with backticks
```
~~~

リストの中のコード

リスト項目の中の fenced コードブロックは、リストのテキストに揃うようインデントする必要があります(通常、- のリストでは 3 スペース、1. のリストでは 4)。リスト内のインデントされたコードブロックには 8 スペースが要ります(リストに 4 + コードに 4)。整列を正しく取るのが、Markdown のより厄介な作業の一つです。

markdown
1. Item with code:

   ```
   code block indented to align
   ```

2. Next item with inline `code`.

- Or indent code 4 spaces beyond
      the list marker (8 total).
08

ブロック引用

基本のブロック引用

> 文字がブロック引用を始めます。すべての行に付けられますが、最初の行だけでも構いません — ほとんどのパーサが連続した行を結合します。ブロック引用は、インデントされたスタイル付きの引用(<blockquote>)として描画されます。引用、コールアウト、抜粋のハイライトに使いましょう。

markdown
> This is a blockquote.
> It can span multiple lines.

> Or just prefix the first line
and continuation lines without >
will still be part of the quote.

複数行のブロック引用

ブロック引用内の段落の分離には、空の > の行を使いましょう(さもないと結合されます)。空行上の > が引用を開いたまま保ちます。段落の間に空行がなければ、テキストが 1 段落として流れます。必ず通常の行で閉じましょう。

markdown
> First paragraph of quote.
>
> Second paragraph of quote.
>
> > Nested quote starts here.
> > Continues on next line.

End of quote.

ネストしたブロック引用

複数の > 文字がネストしたブロック引用を作ります(2 レベルは >>、3 レベルは >>>)。読みやすさのためスペースを加えましょう。深いネスト(3 レベル以上)は読みにくくスタイルも難しくなります — 平坦化を推奨します。レベルごとに HTML 出力でインデントが加わります。

markdown
> Outer quote
>
> > Inner nested quote
> > still nested
>
> Back to outer

> Outer
>> Deeper
>>> Deepest level

他の要素とのブロック引用

ブロック引用はほとんどの Markdown 要素を含められます:見出し、リスト、コード、強調、テーブルさえ。引用の中に留めるには、各行に >(とスペース)を接頭辞として付けましょう。これによりブロック引用がコールアウトに強力になりますが、複雑なコンテンツには慎重な > の整列が要ります。

markdown
> ## Heading in quote
>
> - list item one
> - list item two
>
> *italic* and **bold** work too.
>
> ```
> code block inside quote
> ```

引用付きのブロック引用

Markdown には正式な引用の構文がありません。よくある慣例:新しい行で作者を em ダッシュの接頭辞付きにする、またはセマンティックな引用のために <footer> と <cite> 付きの HTML の <blockquote> を使う。学術的な引用には、ソース付きの脚注を検討しましょう。

markdown
> Be the change you wish to see
> in the world.

> — Mahatma Gandhi

> "Simplicity is the soul of efficiency."
> — Austin Freeman

<blockquote>
  <p>Quote text.</p>
  <footer>— <cite>Author</cite></footer>
</blockquote>
09

テーブル

基本のテーブル

テーブルは、列の分離にパイプ(|)を、ヘッダーの分離にハイフンを使います。ヘッダーの行は必須です。行の端のパイプは省略可能ですが、読みやすさを改善します。列の幅は問題にならず — セルがリサイズします。テーブルは GitHub Flavored Markdown の拡張です。

markdown
| Name  | Age | City     |
|-------|-----|----------|
| Alice | 30  | NYC      |
| Bob   | 25  | London   |
| Carol | 35  | Paris    |

セルの整列

区切りの行の中のコロンが整列を制御します::--- 左、:---: 中央、---: 右です。コロンがなければデフォルトは左です。整列は列全体に適用され、HTML 出力で text-align の CSS を設定します。数値の列(右寄せ)とヘッダー(中央寄せ)に有用です。

markdown
| Left   | Center | Right  |
|:-------|:------:|-------:|
| left   | center | right  |
| L      | C      | R      |

| Default | alignment |
|---------|-----------|
| no mark | left      |

整形付きのテーブル

セルにはインラインの Markdown を含められます:太字、斜体、コード、リンク、打ち消し線、絵文字。ブロック要素(見出し、リスト、コードブロック)はセルの中では機能しないため — 必要なら HTML を使いましょう。読みやすさのためセルの内容は短く保ちます。リテラルのパイプを示すには、バックスラッシュでパイプをエスケープしましょう。

markdown
| Feature    | Status | Notes              |
|------------|:------:|--------------------|
| **Bold**   | done   | *finished*         |
| `code`     | wip    | [docs](docs.md)    |
| ~~old~~    | removed| gone in v2         |
| [link][1]  | done   | see [ref][1]       |

複雑なテーブル

テーブルは多くの行と列に拡張しますが、セルごとは単純なままです。カンマを含むコードスパンスにはバッククォートで包みましょう。リテラルのパイプのエスケープはバックスラッシュとパイプです。複雑なデータ(複数行のセル、ネストしたテーブル)には HTML の <table> が要ります。テーブルが広くなりすぎるなら、リストを検討しましょう。

markdown
| Name  | Role    | Skills              | Available |
|-------|---------|---------------------|:---------:|
| Alice | Lead    | `js`, `ts`, `go`   | yes       |
| Bob   | Junior  | `py`, `sql`         | no        |
| Carol | Senior  | `rust`, `c++`       | yes       |

Escaped pipe: \| literal

テーブルのヒントと制限

Markdown のテーブルには制限があります:セルの結合なし、複数行のコンテンツなし、ブロック要素なし、ネストしたテーブルなし。これらには生の HTML を使いましょう。テーブルは小さく、走査しやすく保ちます。脚注や長いテキストが要るなら、分割しましょう。TablesGenerator.com のようなツールが素早く作る助けになります。

markdown
| A | B |
|---|---|
| 1 | 2 |

Tip: Use \| to escape pipes.

Limitation: no multi-line cells,
no blockquotes, no lists in cells.

For complex tables, use HTML:
<table><tr><td>cell</td></tr></table>
10

脚注

基本の脚注

脚注は、テキストの中の [^id] マーカーと、どこか別の場所の [^id]: 定義を使います。id は数値でも単語でも構いません。レンダラが、クリック可能な上付き数字と末尾の脚注セクションを作ります。GFM、Pandoc、ほとんどのモダンなパーサがサポートします。

markdown
Here is a sentence with a footnote.[^1]

[^1]: This is the footnote text.

Another sentence.[^note]

[^note]: Footnotes can use named labels.

複数の参照

脚注は複数回参照できます — 各 [^id] が同じ定義へリンクします。脚注定義の継続行はインデントします。最初の参照が通常、上付きの数字を得て、以降は同じノートへリンクします。

markdown
Use the term[^term] twice[^term] in the text.

[^term]: A single definition referenced
    multiple times.

First[^1] and second[^1] reference.

[^1]: One definition, two links back.

インライン脚注

インライン脚注(^[text])が、参照の位置に直接ノートの内容を埋め込みます。Pandoc と一部の拡張でサポートされ(GFM コアにはありません)、すべてを 1 箇所に置けますが、読みの流れを中断させ得ます。短いノートに使いましょう。長いものは参照の方が良いです。

markdown
Here is an inline footnote^[The note text
right here in the body.] in a sentence.

Pandoc also supports: ^[inline notes].

And another[^1].

[^1]: Traditional reference style.

脚注の配置

脚注の定義は文書のどこにでも置けます — レンダラが収集し末尾に表示します。継続行はインデントしましょう(4 スペース)。脚注はブロック引用とリスト項目の中でも機能します。ソース内の位置が、出力の位置に影響しません。

markdown
Body text with a note.[^1]

More paragraphs here.

[^1]: Definitions can appear anywhere.
    They float to the bottom in output.

> Even inside blockquotes.[^2]

[^2]: The renderer collects all notes
    and renders them at the end.

コード・整形付きの脚注

脚注の定義は、インラインの Markdown(太字、斜体、コード)と複数段落のコンテンツをサポートします(継続行は 4 スペースでインデント)。脚注内のインデントされたコードブロックには 8 スペースが要ります。脚注は簡潔に保ちましょう — 長い技術的なコンテンツは本文か付録の方が良いです。

markdown
See the API[^api] for details.

[^api]: Use `fetch('/api/data')` to call.
    Supports **bold** and *italic*.
    Multi-paragraph: indent each line.

    Code blocks need indentation:
        indented code inside footnote
11

定義リスト

基本の定義リスト

定義リストは、1 行の用語と、その後にコロン(:)と定義を使います。PHP Markdown Extra、Pandoc、一部の拡張がサポートし(GFM コアにはありません)、<dl><dt><dd> として描画されます。用語集と用語・定義のペアに有用です。

markdown
Term
: Definition of the term.

Markdown
: A lightweight markup language.

HTML
: HyperText Markup Language.

複数の用語

複数の連続した用語(コロンのない)が、単一の定義を共有できます。各用語が <dt> になり、定義が <dd> になります。同じ概念に複数の名前や別名があるときに有用です。用語は別々の行に保ちましょう。

markdown
CSS
Cascading Style Sheets
: A style sheet language.

JS
JavaScript
: A programming language.

Both terms
: Share one definition.

複数の説明

1 つの用語のための複数の連続した定義(各々がコロンで始まる)が、複数の <dd> 要素を作ります。用語のいくつかの異なる意味や側面を列挙するのに有用です。各コロンの行が、独立した定義のエントリです。

markdown
Markdown
: A markup language.
: A tool for writing for the web.

Apple
: A fruit.
: A technology company.

ネストした定義リスト

ネストした定義リストは、外側の定義の中で、内側のリストを(2〜4 スペース)インデントする必要があります。パーサの対応はまちまちです — ネストを扱えないレンダラもあります。複雑な階層的な用語構造には、信頼性のため HTML の <dl> を検討しましょう。ターゲットのレンダラでテストしてください。

markdown
Term
: Definition one.

  Nested term
  : Nested definition.

: Definition two for top term.

ブロック要素付きの定義リスト

定義リストのエントリには、複数の段落、ブロック引用、コードブロックを含められます — 継続するコンテンツは(コロンを超えて)4 スペースでインデントしましょう。内側のコードブロックには合計 8 スペースが要ります。強力ですが脆い部分です。複雑なコンテンツは HTML の <dl> の方が安全です。

markdown
Markdown
:   A markup language.

    With multiple paragraphs in the
    definition (indent 4 spaces).

    > Blockquote inside definition.

:   Second definition with code:

        indented code (8 spaces)
12

目次

自動目次

ほとんどのパーサはデフォルトで目次を自動生成しません。一部(toc プラグイン付きの marked、MDX)は [TOC] や {:toc} のプレースホルダーをサポートします。Doctoc や markdown-toc のようなツールが見出しから生成します。静的サイトでは、TOC のコンポーネントがビルド時か実行時に見出しのアンカーを読みます。

markdown
## Table of Contents

1. [Introduction](#introduction)
2. [Installation](#installation)
3. [Usage](#usage)
4. [FAQ](#faq)

Some parsers auto-generate a TOC
with `[TOC]` or `{:toc}` markers.

手動の目次

手動の目次は、見出しのアンカーへのリンクのネストしたリストです。アンカーの id は見出しのテキストから導かれます(小文字、スペースはハイフン、句読点は除去)。見出しの階層を反映するようインデントしましょう。見出しが変わったら手動で更新するか、ジェネレータを使います。

markdown
# My Document

## Contents
- [Intro](#intro)
- [Setup](#setup)
  - [Prerequisites](#prerequisites)
  - [Install](#install)
- [Usage](#usage)

## Intro
...

アンカー生成のルール

アンカー生成はパーサにより異なります。よくあるルール:小文字化、スペースはハイフンへ、句読点の除去、英数字の維持です。GitHub は絵文字といくつかの Unicode を保ちます。数字とドットはしばしば除去されます。確信がなければ、実際の id を見つけるため、描画された HTML を検査しましょう。

markdown
## Hello World        -> #hello-world
## Hello, World!      -> #hello-world
## C++ & Rust         -> #c--rust
## Uber Heading       -> #uber-heading
## 1. Getting Started  -> #1-getting-started
## API v2.0           -> #api-v20

カスタムアンカー ID

信頼できるアンカーのためには、明示的な ID を加えましょう。{#id} の属性構文が Pandoc、marked、一部の拡張で機能します。HTML の <a id="..."> のトリックはどこでも機能します — 見出しの前か内側に置きましょう。カスタム ID は、見出しのテキストの変化に耐えます。

markdown
## Heading {#custom-id}

<a id="my-anchor"></a>
## Heading

## Heading<a id="also"></a>

[link to custom](#custom-id)

TOC のナビゲーションと戻りリンク

長い文書のナビゲーション改善に、最上部へ戻るリンクが役立ちます。折りたたみ可能な目次を作るのが、<details>/<summary> の HTML です — サイドバーや長い README に最適です。スムーズなナビゲーションのためにアンカーリンクと組み合わせましょう。固定ヘッダーのオフセットには、CSS で scroll-margin-top を加えましょう。

markdown
## Section

Content here.

[Back to top](#table-of-contents)

---

<details>
<summary>Table of Contents</summary>

- [Section 1](#section-1)
- [Section 2](#section-2)
</details>
13

絵文字と特殊文字

絵文字のショートコード

絵文字のショートコード(:name:)が GitHub/GitLab でサポートされています(EmojiOne/Twemoji のセットを使用)。名前付きの絵文字が数千あります。ショートコードは便利ですが移植性がなく — 非 GFM のパーサではリテラルに描画され得ます。最大の互換性のためには、生の Unicode 絵文字を使いましょう。

markdown
:smile: :heart: :thumbsup: :rocket:

GFM supports shortcodes:
:sparkles: new feature :tada:

:checkered_flag: launch!
:bug: fixed issue #42

よく使う絵文字

ほとんどのモダンなエディタとレンダラが生の Unicode 絵文字を直接扱います — 貼り付けるだけです。ショートコードは GitHub 固有です。絵文字はトーンとステータスを伝えられます(結果にはチェック/クロス、バグには bug)。正式なドキュメントでは控えめに、README と変更ログでは素晴らしいです。

markdown
:smile: smile    :heart: heart    :thumbsup: thumbsup
:rocket: rocket   :star: star     :warning: warning
:check: check    :x: cross       :bulb: bulb
:fire: fire      :tada: tada      :bug: bug
:book: book      :wrench: wrench  :zap: zap

HTML エンティティ

Markdown は HTML へ通すため、HTML エンティティが機能します。リテラルのアンパサンドには(URL/属性では特に)&amp;、角括弧には &lt; &gt;、記号には &copy; &reg; &trade; を使いましょう。数値形式(&#169;)と 16 進(&#x00A9;)が任意の Unicode 文字をカバーします。

markdown
&amp;  &lt;  &gt;  &quot;  &apos;

&copy;  &reg;  &trade;

&mdash; &ndash; &hellip;

&#169;  &#x00A9;

Use &amp; to show a literal &.

特殊文字

Markdown はデフォルトで、プレーンな句読点をタイポグラフィの文字(スマートクォート)に変換しません — HTML エンティティか Unicode の貼り付けを使いましょう。em ダッシュとカーリークォートがタイポグラフィを改善します。これらを自動修正するエディタもあります。矢印と記号には、エンティティが最も明快です。

markdown
-- em dash (or &mdash;)
-- en dash (or &ndash;)
... ellipsis (or &hellip;)
' ' curly quotes (&lsquo; &rsquo;)
" " curly quotes (&ldquo; &rdquo;)
-> arrow (or &rarr;)
(tm) (r) (c)

絵文字と Markdown の組み合わせ

絵文字はすべての Markdown 要素と組み合わせられます:見出し、リスト、太字、リンク、ブロック引用。変更ログ、README、issue テンプレートへ視覚的な手がかりを加えます。絵文字の使用は一貫させましょう(例えば、変更ログの慣例を保つ)。正式/学術的な文章では絵文字を避けましょう。

markdown
## New Features

- :sparkles: Added dark mode
- :bug: Fixed login bug
- :memo: Updated docs

**Status:** :white_check_mark: Ready

> :warning: **Warning:** Deprecated!

[:book: Read the docs](/docs)
14

Mermaid 図

Mermaid のフローチャート

Mermaid はテキストベースの図言語で、GitHub、GitLab、多くの静的サイトジェネレータが描画します。Mermaid のコードは mermaid の fenced ブロックで包みましょう。flowchart TD(上から下)か LR(左から右)が方向を定義します。ノードには、異なる形状のために []、{}、() を使います。

markdown
```mermaid
flowchart TD
    A[Start] --> B{Is it?}
    B -->|Yes| C[Do it]
    B -->|No| D[Do not]
    C --> E[End]
    D --> E
```

Mermaid のシーケンス図

シーケンス図が、時間をかけて参加者の間のやり取りを示します。->> が実線の矢印(リクエスト)で、-->> が破線の矢印(レスポンス)です。actor の宣言は participant です。API フロー、プロトコル、メッセージパッシングの文書化に有用です。GitHub で自動描画されます。

markdown
```mermaid
sequenceDiagram
    participant A as Alice
    participant B as Bob
    A->>B: Hello Bob!
    B-->>A: Hi Alice!
    A->>B: How are you?
    B-->>A: Good, thanks!
```

Mermaid のクラス図

クラス図がオブジェクト指向の構造をモデル化します。+ が public、- が private、# が protected で、継承を示すのが <|-- です。Mermaid は関連、合成、インターフェースをサポートします。Markdown に直接コードアーキテクチャを文書化するのに最適です。

markdown
```mermaid
classDiagram
    class Animal {
        +String name
        +int age
        +makeSound() void
    }
    class Dog {
        +fetch() void
    }
    Animal <|-- Dog
```

Mermaid の状態図

状態図が状態の遷移を示します。開始/終了状態を印付けるのが [*] で、イベントをラベルにする矢印は state --> state: event です。プロトコル、UI の状態、オブジェクトのライフサイクルの文書化に有用です。モダンな構文が stateDiagram-v2 です。

markdown
```mermaid
stateDiagram-v2
    [*] --> Idle
    Idle --> Processing: start
    Processing --> Done: complete
    Processing --> Error: fail
    Done --> [*]
    Error --> [*]
```

Mermaid のガントチャート

ガントチャートがプロジェクトのスケジュールを可視化します。日付のパースの設定は dateFormat です。タスクは id、開始、duration(例:7d)を使い、タスクの連鎖は 'after a1' です。関連するタスクはセクションがグループ化します。README とプロジェクト計画に有用です — 外部ツールなしで GitHub 上で自動描画されます。

markdown
```mermaid
gantt
    title Project Schedule
    dateFormat YYYY-MM-DD
    section Design
    Spec        :a1, 2024-01-01, 7d
    Mockups     :after a1, 5d
    section Build
    Develop     :2024-01-13, 14d
    Test        :7d
```

Mermaid の円グラフ

円グラフが比率をパーセンテージで示します(値は相対的です)。タイトルは省略可能で、ラベルは引用符の中、コロンの後に値を置きます。Mermaid は git グラフ、ER 図、ジャーニーマップ、マインドマップもサポートします — 対応するプラットフォームの Markdown 上ですべて描画できます。

markdown
```mermaid
pie title Browser Market Share
    "Chrome" : 65
    "Safari" : 18
    "Edge" : 5
    "Firefox" : 3
    "Other" : 9
```
15

GitHub Flavored Markdown

タスクリスト(GFM)

GitHub Flavored Markdown(GFM)のタスクリストが、GitHub 上でインタラクティブなチェックボックスとして描画されます。チェックは [x]、未チェックは [ ] です。issue、PR、コメント、README で機能します。issue のリストにプログレスバーが現れます。この構文は今や、GitHub を超えて広くサポートされています。

markdown
- [x] Done task
- [ ] Todo task
- [ ] Another todo

## Project Status
- [x] Design
- [x] Implement
- [ ] Test
- [ ] Deploy

打ち消し線(GFM)

GFM が標準の Markdown へ打ち消し線(~~text~~)を加えます。行をまたいで機能し、他の整形とも組み合わせられます。<del> として描画されます。元々は GFM の拡張でしたが、今や CommonMark の仕様への追加にあります。編集と非推奨の表示に有用です。

markdown
~~deleted text~~

old ~~price~~ new

~~this line is wrong~~

Combine: **bold ~~struck~~ text**

~~multi-line
strikethrough~~

テーブル(GFM)

テーブルは GFM の機能です(元の Markdown ではありません)。ヘッダーの行と区切り付きのパイプ構文が必須です。GFM のテーブルは整列、インラインの整形、エスケープされたパイプに対応します。複雑なテーブル(結合、ネスト)には、HTML へフォールバックしましょう。

markdown
| Feature    | Status |
|------------|:------:|
| Tables     | yes    |
| Tasks      | yes    |
| Auto-links | yes    |

Tables are core to GFM, not in
the original Markdown spec.

GitHub アラート

GitHub アラート(2023+)は、ブロック引用の最初の行に [!TYPE] のマーカーを使います:NOTE、TIP、IMPORTANT、WARNING、CAUTION です。GitHub 上で、はっきり異なる色とアイコンで描画されます。README とドキュメントのコールアウトに最適です。この構文は GitHub 固有です。

markdown
> [!NOTE]
> Useful information that users
> should know.

> [!WARNING]
> Urgent info about risks.

> [!IMPORTANT]
> Key information.

> [!TIP]
> Helpful advice.

許可されない生の HTML

GFM は安全のため生の HTML をフィルタします — <script>、<style>、<title>、時には <iframe>、イベントハンドラが剥ぎ取られます。これが、ユーザー生成コンテンツでの XSS を防ぎます。<details>、<kbd>、<sup> のような安全な HTML は通ります。HTML を混ぜるときは、あなたのレンダラの許可リストを知りましょう。

markdown
GFM sanitizes some HTML tags:

<script>alert('xss')</script>
<style>body { color: red; }</style>
<title>Page</title>

These are stripped for security.

自動リンク(GFM)

GFM は、角括弧なしで裸の URL(https://...)と www. のドメインを自動リンクします。移植性のためには、角括弧(<url>)がすべての派生で機能します。自動リンクは思いがけないことがあります — 他のテキストが隣接する状態で URL をリテラルに表示したいときは、角括弧を使いましょう。

markdown
Visit https://example.com now.

www.google.com auto-links too.

<https://example.com> always works.

In GFM, bare URLs and www. links
become clickable automatically.
16

拡張構文

ハイライト

==text== のハイライト構文は拡張です(GFM や CommonMark にはありません)— プラグイン付きの Markdown-it のような一部のパーサがサポートします。普遍的にサポートされているのが、HTML の <mark> タグです。キーとなる用語の強調にハイライトを使い、乱用は効果を減らします。

markdown
==highlighted text==

<mark>HTML highlight</mark>

Some parsers (not GFM core) support
==this syntax== for highlighting.

Use <mark> for universal support.

下付きと上付き

下付き(~text~)と上付き(^text^)は Pandoc/markdown-it の拡張で、標準ではありません。普遍的な描画には、HTML の <sub>/<sup> か Unicode を使いましょう。Markdown で書かれた科学・数学のコンテンツに有用です。

markdown
H~2~O (subscript)

x^2^ (superscript)

E = mc^2^

H~2~SO~4~

Pandoc/R Markdown support ~ and ^.

属性構文

{#id .class key=val} の属性構文(Pandoc、一部の markdown-it プラグイン)が、要素へ HTML 属性を付けます。スタイリングのフック、カスタムアンカー、リンクのターゲットに有用です。移植性がなく — 対応しないパーサではリテラルのテキストへフォールバックします。控えめに使いましょう。

markdown
## Heading {#id .class}

![alt](img.png){width=50%}

[link](url){target=_blank}

> Quote {.callout}

カスタムコンテナ

カスタムコンテナ(:::type ... :::)が、VuePress、Docusaurus、VitePress や同様のドキュメントツールでサポートされています。スタイル付きのコールアウトボックスとして描画され、タイプが CSS クラスへ対応します。テーマ化されたドキュメントに最適ですが、プレーンな Markdown レンダラへの移植性はありません。

markdown
:::note
This is a note container.
:::

:::warning
This is a warning.
:::

::: details Open me
Hidden content.
:::

数式と LaTeX(KaTeX)

数式の対応はレンダラに依存します:GitHub は $...$ のインラインと $$...$$ のブロックに対応します(MathJax/KaTeX 付き)。すべての Markdown パーサが数式に対応するわけではありません。最大の互換性のためには、数式を画像へ描画するか MathJax を直接使いましょう。科学・技術のドキュメントに有用です。

markdown
Inline: $E = mc^2$ in a sentence.

Block:

$$
\int_0^\infty e^{-x^2} dx = \frac{\sqrt{\pi}}{2}
$$

Some parsers support \( \) and
\[ \] delimiters too.
17

ツールとエディタ

VS Code

VS Code には組み込みの Markdown プレビューと豊かな拡張のエコシステムがあります。ショートカット(太字、目次、プレビュー)を加えるのが Markdown All in One で、スタイルを強制するのが markdownlint、図、数式、エクスポートに対応するのが Preview Enhanced です。快適な編集のため word wrap を設定しましょう。

markdown
# VS Code Markdown extensions:
- Markdown All in One
- Markdown Preview Enhanced
- markdownlint
- Pandoc

# Built-in preview: Ctrl+Shift+V
# Side-by-side: Ctrl+K V

# Settings:
"[markdown]": {
  "editor.wordWrap": "on",
  "editor.quickSuggestions": true
}

Typora

Typora が人気のある WYSIWYG Markdown エディタです — タイプするにつれインラインで描画し、分割ペインのワークフローを不要にします。GFM、テーブル、コード fence、数式、Mermaid に対応します。組み込みのツールで多くの形式へエクスポートします。有料ですが洗練されており、執筆中心のワークフローに最適です。

markdown
Typora: a WYSIWYG Markdown editor.

- Live rendering as you type
- No split pane (instant preview)
- Supports tables, diagrams, math
- Export to PDF, HTML, Word, LaTeX
- Themes and custom CSS

Shortcuts:
- Ctrl+/ toggle source code mode
- Ctrl+B bold, Ctrl+I italic

Obsidian

Obsidian がノートをローカルの Markdown ファイルとして保存し、強力な機能を持ちます:wiki リンク、バックリンク、グラフビュー、タグです。Markdown を、コールアウト、埋め込み、Dataview で拡張します。Zettelkasten と個人のナレッジマネジメントに理想的です。個人利用は無料です。

markdown
Obsidian: a Markdown knowledge base.

- Plain-text .md files (local-first)
- Bidirectional [[wiki links]]
- #tags and nested tags
- Backlinks and graph view
- Plugins for almost everything
- Callouts: > [!note] Title

[[note|alias]] for renamed links.

Markdown Lint

markdownlint が Markdown ファイルをまたいで一貫したスタイルを強制します。ルールの設定は .markdownlint.json です。よくある無効化:散文には MD013(行の長さ)、HTML が必要なときは MD033(インライン HTML)です。コード fence に言語タグを付けるよう促すのが MD040 です。CI とエディタと統合します。

markdown
# .markdownlint.json (config)

{
  "MD013": false,
  "MD024": { "siblings_only": true },
  "MD033": false,
  "default": true
}

# Rules (examples):
# MD013 line length
# MD024 no duplicate headings
# MD033 no inline HTML
# MD040 fenced code needs language

Pandoc

Pandoc が文書変換の「スイスアーミーナイフ」です — Markdown と HTML、PDF、Word、LaTeX、EPUB、スライドの相互変換。Markdown の拡張(引用、数式、定義リスト、生の属性)に対応します。スタンドアロンの文書を作るのが -s フラグです。学術と出版のワークフローには不可欠です。

markdown
# Convert Markdown to many formats:

pandoc input.md -o output.html
pandoc input.md -o output.pdf
pandoc input.md -o output.docx
pandoc input.md -o slides.pdf

# Markdown to a self-contained HTML:
pandoc input.md -s -o output.html

# With a table of contents:
pandoc input.md --toc -o output.html

# Support extensions:
pandoc -f markdown+smart input.md

オンラインエディタ

オンラインエディタが、素早い編集と共有に最適です。フル機能の単独エディタが StackEdit と Dillinger で、リアルタイムの共同編集を加えるのが HackMD/HedgeDoc です。GitHub の Web エディタには Preview タブがあります。すべてが標準の Markdown に対応し、GFM の機能が最良に機能するのは GitHub のエディタです。

markdown
Popular online Markdown editors:

- StackEdit (stackedit.io)
  Full-featured, syncs to cloud.

- Dillinger (dillinger.io)
  Clean, exports to many formats.

- HackMD / HedgeDoc
  Real-time collaborative editing.

- GitHub web editor
  Preview tab for .md files.

- Markdown Live Preview
  Lightweight, instant preview.
18

ベストプラクティス

読みやすさファースト

Markdown の核心の原則は、プレーンテキストとしての読みやすさです。最も読みやすい構文を推奨しましょう:# の見出し、- のリスト、**太字** です。過度のネストと過剰な整形は避けましょう。生のソースがテキストエディタで快く読めるなら、Markdown をうまく使えています。

markdown
# Good: readable as plain text
## Section
Use **bold** for emphasis, not
__bold__ (asterisks are clearer).

# Bad: hard to read raw
##Section or ***overkill***

Tip: Preview raw Markdown often.
If it reads well as text, it is good.

行の長さとラップ

2 つの有効なアプローチがあります:ハードラップ(1 行 1 文)がきれいな git diff と楽な編集を与え、ソフトラップ(1 行 1 段落)が再フローの作業を避けます。プロジェクトごとに 1 つ選び、一貫させましょう。それに合わせ、エディタのラップ幅(通常 80〜120 文字)を設定しましょう。

markdown
# Hard wrap (one sentence per line):
This is sentence one.
This is sentence two.

# Soft wrap (paragraph as one line):
This is a long paragraph that
continues on without hard breaks,
relying on editor wrapping.

# Many projects prefer one sentence
# per line for clean git diffs.

一貫性

Markdown は同じ結果のために複数の構文を提供します(太字の ** 対 __、リストの - 対 * 対 +)。プロジェクトごとに 1 つの慣例を選び、markdownlint で強制しましょう。一貫性が、読者と貢献者の認知負荷を減らし、自動処理を容易にします。

markdown
# Pick one style and stick to it:

- Use - for lists (not * or +)
- Use ** for bold (not __)
- Use * for italic (not _)
- Use ``` for fences (not ~~~)
- Use # for headings (not ===/--)

Consistent style is more
maintainable and professional.

リンクのベストプラクティス

長い URL には参照リンクを使い、散文を読みやすく保ちましょう。短いローカルの参照にはインラインリンクです。記述的なリンクテキストがアクセシビリティと SEO を改善します — 「ここをクリック」は避けましょう。タイトルがツールチップとして文脈を加えます。参照の定義は、セクションか文書の末尾にまとめましょう。

markdown
# Reference links for long URLs:
See the [docs][docs] for details.

[docs]: https://example.com/very/long/url

# Inline for short links:
Edit [index.js](index.js).

# Title for context:
[API](api.md "REST API reference")

Keep link text descriptive,
not 'click here' or 'link'.

アクセシビリティ

Markdown でもアクセシビリティは効きます:画像のための意味のある alt テキスト(装飾的なものには空の alt)、記述的なリンクテキスト(「ここをクリック」ではない)、適切な見出しの階層(レベルを飛ばさない)、Markdown が届かない所でのセマンティックな HTML(kbd、abbr、cite)です。スクリーンリーダーがこれらに依存しています。

markdown
# Always add alt text to images:
![Diagram of the system](diagram.png)

# Empty alt for decorative images:
![](spacer.png)

# Descriptive link text:
[Read the installation guide](install.md)

# Avoid: [click here](url)
# Use heading hierarchy in order.

# Use semantic HTML when needed:
<kbd>Ctrl</kbd> + <kbd>C</kbd>

よくある間違い

よくある落とし穴:ブロック要素(リスト、引用、コード)の周りの空行の欠落、ネストしたリストでの不一致なインデント、閉じていないコード fence、タブとスペースの混在です。公開前には必ずプレビューしましょう。問題の自動検出には markdownlint を実行し、ターゲットのレンダラでテストしましょう。

markdown
# Missing blank line before lists:
Text
- item  # may merge with text!

# Fix:
Text

- item

# Unclosed code fence:
```
code
# (missing closing fence)

# Inconsistent list indentation:
- a
  - b (2 spaces)
   - c (3 spaces — may break)

Was this helpful?

Learning path

Learn from scratch

Learn this language from the ground up with structured lessons.