はじめに
見出しと段落
見出しには # を使いましょう(1〜6 レベル)。代替の構文は、H1 に ===、H2 に --- です。段落の間には空行が必要です。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 段落に結合されるソフトな折り返しです。段落を分けるには必ず空行を残しましょう。
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 のコメント(<!-- -->)がほとんどのレンダラで機能し、出力では隠れます。[//]: # のトリックが、空のリンク参照を使ってメモを加えます。コメントは生のソースでは依然見えます。
<!-- HTML comments work in most Markdown -->
[//]: # (This is a comment)
[//]: # "Another comment style"
<!--
Multi-line comment
not rendered in output
-->空白とインデント
行頭の 4 スペースがテキストをコードブロックに変えます — 意図しないインデントに注意しましょう。ネストしたリストではインデントが効きます(レベルごとに 2〜4 スペース)。タブは通常 4 スペースとして扱われます。パーサ間の描画問題を避けるため、スペースを一貫して使いましょう。
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>)を作ります。ハイフンが最も一般的です。文字の間のスペースは許されます。明快さのため、水平罫線の前後に空行を置きましょう。---(罫線)を #(見出し)と混同しないよう注意してください。
---
***
___
* * *
Text above
---
Text belowテキストの整形
太字と Strong
二重のアスタリスクかア ンダースコアが太字(<strong>)を作ります。アンダースコアは単語の途中では機能しないため(snake_case)、アスタリスクが推奨です。太字の中に他の強調をネストできます。フォールバックとして HTML の <strong> タグも機能します。
**bold text**
__also bold__
**bold with *italic* inside**
<strong>HTML bold also works</strong>
**bold**斜体と Emphasis
単一のアスタリスクかアンダースコアが斜体(<em>)を作ります。アスタリスクは単語の途中でも機能し、アンダースコアは語内のアンダースコアをリテラルとして扱います(そのため no_italic_here)。フォールバックには <em> を使いましょう。斜体はスタイリングだけでなく強調のためのものです。
*italic text*
_also italic_
*italic*
<em>HTML italic</em>
normal *italic* normal太字 + 斜体の組み合わせ
三重のアスタリスク/アンダースコアが太字と斜体の両方を作ります。ネストもできます:太字の中に斜体、またはその逆。描画では順序は問題になりませんが、読みやすさのため一貫させるべきです。
***bold and italic***
___also both___
**_bold and italic_**
*__bold and italic__*
combine **bold** and *italic*打ち消し線
二重のチルダ(~~)が打ち消し線を作ります。GitHub Flavored Markdown の一部で、今では広くサポートされています。HTML の <del> と <s> タグが等価のフォールバックです。標準(元の)Markdown には打ち消し線が含まれていません。
~~strikethrough~~
~~crossed out text~~
<del>HTML delete</del>
<s>HTML strikethrough</s>
~~done~~ and ~~pending~~Mark / ハイライト
ハイライトのための二重イコール(==)は、一部のパーサがサポートする拡張です(GFM コアにはありません)。HTML の <mark> タグが普遍的に機能します。キーとなる用語への注意を引くため、ハイライトは控えめに使いましょう — 乱用は効果を減らします。
==highlighted text==
<mark>HTML mark</mark>
This is ==important== text.
Compare **bold**, *italic*, ==mark==.下付きと上付き
チルダ(下付き)とキャレット(上付き)の構文(~ ~ と ^ ^)は拡張であり、標準の Markdown にも GFM にもありません — Pandoc、R Markdown、その他少数がサポートします。普遍的な対応には、HTML の <sub> と <sup> か Unicode 文字を使いましょう。
H~2~O is water
E = mc^2^
x^2^ + y^2^ = r^2^
1st^st^ January
CO~2~ emissionsリスト
順序なしリスト
順序なしリストの項目には -、*、+ を使えます — 1 つ選び、一貫させましょう(- が最も一般的です)。ネストした項目には 2〜4 スペ ースのインデントを付けます。同じリストでのマーカーの混在は、一部のパーサで問題を引き起こし得ます。1 行 1 項目です。
- 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. を使います。
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 レベル以上)は読みやすさを損なうため — 再構成を検討しましょう。インデントは一貫させましょう。
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 トラッカー、進捗管理に最適です。
- [x] completed task
- [ ] incomplete task
- [ ] another todo
1. [x] done
2. [ ] not done
- [x] Write the docs
- [ ] Review PR
- [ ] DeployLoose と Tight リスト
リストの項目が空行で分かれていれば、リストは「loose」です(各項目が <p> で包まれる)。空行がなければ「tight」です(<p> のラッパーなし)。これが HTML 出力の間隔に影響します。段落のラップを制御するため、空行は意図的に加えましょう。
- tight item
- tight item
- tight item
- loose item
- loose item
- loose item複数段落を含むリスト
リスト項目に複数の段落やブロック要素を含めるには、継続行を 4 スペースでインデントします(またはリストマーカーの内容に揃える)。サブブロックは空行で分けます。複雑なリスト構造には不可欠ですが、間違いやすい部分です。
- First item
Second paragraph of first item.
- Second item
> A blockquote inside a list item.
>
> Must be indented to align.
- Third itemリンク
インラインリンク
インラインリンクは [text](url) です。引用符の中の省略可能なタイトルが、ホバー時のツールチップとして現れます。サイ ト内ナビゲーションには相対リンクが機能します。アンカーリンク(#id)が、一致する id を持つ要素へ跳びます。URL にはスペースを含めてはならず — スペースには %20 を使いましょう。
[link text](https://example.com)
[link with title](https://example.com "Title here")
[relative link](/about)
[anchor](#section-id)参照リンク
参照リンクが、URL を分離してテキストを読みやすく保ちます。参照は文書のどこでも定義できます([ref]: url)。参照の定義は描画されません。暗黙の形式 [text][] が、テキスト自体を参照の id として使います。参照は再利用できます。
[link text][ref]
[ref]: https://example.com "Optional title"
[link text][1]
[1]: https://example.com
[link text]
[link text]: https://example.com自動リンクと URL
裸の URL は GitHub Flavored Markdown で自動リンクされます。標準準拠のためには、URL を角括弧(<url>)で囲みましょう。角括弧の形式はすべての Markdown の派生で機能します。自動リンクは一部のパーサで無効化できます。
https://example.com
<https://example.com>
<http://www.google.com>
Auto-linking bare URLs is supported
in GFM: visit https://example.com now.メールの自動リンク
角括弧の中のメールアドレスが、クリック可能な mailto: リンクになります。元の Markdown 仕様は <text@domain> の形式をサポートしていました。スパム収集を減らすため、メールアドレスを難読化するレンダラもあります。公開サイトでのより良いスパム保護のためには、問い合わせフォームを使いましょう。
<[email protected]>
Contact: <[email protected]>
<John Doe <[email protected]>>
Mailto links work in most renderers.リンクのタイトル
リンクのタイトルは、ホバー時のツールチップとして現れます。タイトルの周りにはダブルかシングルの引用符を使いましょう。タイトルは省略可能で、純粋に UX/SEO のヒントです。リンクのテキストの代わりにはならず — スクリーンリーダーが無視することがあります。タイトルは簡潔に保ちましょう。
[hover for title](https://example.com "Example Site")
[reference with title][a]
[a]: https://example.com "Example Site"
[title with single quotes](https://example.com 'Single')内部リンクとアンカーリンク
見出しのアンカーは、ほとんどのパーサで見出しのテキストから(小文字化、スペースはハイフンへ、句読点は除去)自動生成されます。カスタム ID には、HTML の <a id="..."> か {#id} の属性拡張(Pandoc/marked)を使いましょう。目次にはアンカーリンクが不可欠です。
## Section Heading
[jump to Section](#section-heading)
[back to top](#top)
<a id="custom-id"></a>
[custom anchor](#custom-id)
## Heading {#explicit-id}画像
基本の画像
画像の構文はリンクのようですが、! が接頭辞です。アクセシビリティのため alt テキストは必須です — スクリーンリーダーのために画像を説明し、画像の読み込みに失敗したとき表示されます。パスは相対、絶対、URL のいずれかです。タイトルは省略可能です。


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


リンク付き画像
リンクの構文の中に画像の構文をネストすれば、画像をリンクで包めます:[](url)。フルサイズへのリンクを持つサムネイル、CI のステータスへのリンクを持つバッジ、ホームへのリンクを持つロゴでよくあります。画像だけでなく宛先を記述する alt テキストを保ちましょう。
[](https://example.com/full)
[](/)
[](https://ci.example.com)参照画像
参照画像は、リンクと同じ参照スタイルを ! 接頭辞付きで使います。画像の参照は一度定義し、再利用しましょう。同じ画像が複数回現れるときや、画像の多い段落を読みやすく保つときに有用です。
![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)は {width=300} に対応しています。
<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>インラインコードとエスケープ
インラインコード
インラインコードは単一のバッククォートで包みましょう。コードの中にバッククォートを示すには、区切りとして(またはそれ以上の)二重のバッククォートを使います。インラインコードは等幅で描画され、Markdown としてパースされません。ファイル名、コマンド、コードの識別子に最適です。
Use the `printf()` function.
Inline code: `const x = 42;`
Code with backticks: ``use `code` here``
A `<div>` element.コードスパンでのバッククォートのエスケープ
コードスパンの中にバッククォートを含めるには、内側に現れるものより多いバッククォートを区切りとして使います:単一のバッククォートの周りに二重のバッククォート。コードスパンの外では、バッククォートはバックスラッシュでエスケープしましょう。閉じる fence は開く長さと一致しなければなりません。
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 スペースは自動的に剥ぎ取られます。
` spaced ` (spaces preserved)
` code ` with one space pad
`function f() { return; }`
` multi word code `バックスラッシュエスケープ
バックスラッシュが特殊な Markdown 文字をエスケープします:バッククォート、アスタリスク、アンダースコア、波括弧、角括弧、丸括弧、ハッシュ、プラス、マイナス、ドット、感嘆符、バックスラッシュ自体です。エスケープすると文字がリテラルとして描画されます。フォーマットとして解釈される文字だけをエスケープしましょう。
\*not italic\*
\_not italic\_
\#not a heading
\[not a link](url)
\`not code\`
\\backslash itself
\!not an imageエスケープすべき文字
これが Markdown でエスケープ可能な文字です。すべてがどこでもエスケープを要するわけではありません — # は行頭でのみ効き、- はリストの文脈で、など。迷ったらエスケープしましょう。波括弧と丸括弧は、通常特定の文脈(リンク、テンプレート文字列)でだけエスケープが必要です。
\\ backslash
\` backtick
\* asterisk
\_ underscore
\{ \} curly braces
\[ \] square brackets
\( \) parentheses
\# hash
\+ plus
\- minus
\. dot
\! exclamationコードブロック
インデントされたコードブロック
4 スペース(かタブ)のインデントがコードブロックを作ります。インデントされたコードブロックには構文ハイライトと言語タグがなく、リスト項目の中では使えません(継続として扱われます)。新しいコンテンツには fenced コードブロックを推奨します — インデントされたブロックはレガシーです。
Normal paragraph.
// indented code (4 spaces)
function hello() {
console.log("hi");
}
Back to normal text.Fenced コードブロック
三重のバッククォートか三重のチルダが fenced コードブロックを作ります。fence がインデントされたブロックより推奨です — 曖昧さがなく言語のヒントをサポートします。コード自体が三重のバッククォートを含むとき、チルダ(~~~)が有用です。fence は同じ文字数で必ず閉じましょう。
```
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。言語が未知なら、素の等幅のため省きましょう。
```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 は開く長さと一致しなければなりません。
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 のより厄介な作業の一つです。
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).ブロック引用
基本のブロック引用
> 文字がブロック引用を始めます。すべての行に付けられますが、最初の行だけでも構いません — ほとんどのパーサが連続した行を結合します。ブロック引用は、インデントされたスタイル付きの引用(<blockquote>)として描画されます。引用、コールアウト、抜粋のハイライトに使いましょう。
> 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 段落として流れます。必ず通常の行で閉じましょう。
> First paragraph of quote.
>
> Second paragraph of quote.
>
> > Nested quote starts here.
> > Continues on next line.
End of quote.ネストしたブロック引用
複数の > 文字がネストしたブロック引用を作ります(2 レベルは >>、3 レベルは >>>)。読みやすさのためスペースを加えましょう。深いネスト(3 レベル以上)は読みにくくスタイルも難しくなります — 平坦化を推奨します。レベルごとに HTML 出力でインデントが加わります。
> Outer quote
>
> > Inner nested quote
> > still nested
>
> Back to outer
> Outer
>> Deeper
>>> Deepest level他の要素とのブロック引用
ブロック引用はほとんどの 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> を使う。学術的な引用には、ソース付きの脚注を検討しましょう。
> 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>テーブル
基本のテーブル
テーブルは、列の分離にパイプ(|)を、ヘッダーの分離にハイフンを使います。ヘッダーの行は必須です。行の端のパイプは省略可能ですが、読みやすさを改善します。列の幅は問題にならず — セルがリサイズします。テーブルは GitHub Flavored Markdown の拡張です。
| Name | Age | City |
|-------|-----|----------|
| Alice | 30 | NYC |
| Bob | 25 | London |
| Carol | 35 | Paris |セルの整列
区切りの行の中のコロンが整列を制御します::--- 左、:---: 中央、---: 右です。コロンがなければデフォルトは左です。整列は列全体に適用され、HTML 出力で text-align の CSS を設定します。数値の列(右寄せ)とヘッダー(中央寄せ)に有用です。
| Left | Center | Right |
|:-------|:------:|-------:|
| left | center | right |
| L | C | R |
| Default | alignment |
|---------|-----------|
| no mark | left |整形付きのテーブル
セルにはインラインの Markdown を含められます:太字、斜体、コード、リンク、打ち消し線、絵文字。ブロック要素(見出し、リスト、コードブロック)はセルの中では機能しないため — 必要なら HTML を使いましょう。読みやすさのためセルの内容は短く保ちます。リテラルのパイプを示すには、バックスラッシュでパイプをエスケープしましょう。
| Feature | Status | Notes |
|------------|:------:|--------------------|
| **Bold** | done | *finished* |
| `code` | wip | [docs](docs.md) |
| ~~old~~ | removed| gone in v2 |
| [link][1] | done | see [ref][1] |複雑なテーブル
テーブルは多くの行と列に拡張しますが、セルごとは単純なままです。カンマを含むコードスパンスにはバッククォートで包みましょう。リテラルのパイプのエスケープはバックスラッシュとパイプです。複雑なデータ(複数行のセル、ネストしたテーブル)には HTML の <table> が要ります。テーブルが広くなりすぎるなら、リストを検討しましょう。
| 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 のようなツールが素早く作る助けになります。
| 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>脚注
基本の脚注
脚注は、テキストの中の [^id] マーカーと、どこか別の場所の [^id]: 定義を使います。id は数値でも単語でも構いません。レンダラが、クリック可能な上付き数字と末尾の脚注セクションを作ります。GFM、Pandoc、ほとんどのモダンなパーサがサポートします。
Here is a sentence with a footnote.[^1]
[^1]: This is the footnote text.
Another sentence.[^note]
[^note]: Footnotes can use named labels.複数の参照
脚注は複数回参照できます — 各 [^id] が同じ定義へリンクします。脚注定義の継続行はインデントします。最初の参照が通常、上付きの数字を得て、以降は同じノートへリンクします。
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 箇所に置けますが、読みの流れを中断させ得ます。短いノートに使いましょう。長いものは参照の方が良いです。
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 スペース)。脚注はブロック引用とリスト項目の中でも機能します。ソース内の位置が、出力の位置に影響しません。
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 スペースが要ります。脚注は簡潔に保ちましょう — 長い技術的なコンテンツは本文か付録の方が良いです。
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定義リスト
基本の定義リスト
定義リストは、1 行の用語と、その後にコロン(:)と定義を使います。PHP Markdown Extra、Pandoc、一部の拡張がサポートし(GFM コアにはありません)、<dl><dt><dd> として描画されます。用語集と用語・定義のペアに有用です。
Term
: Definition of the term.
Markdown
: A lightweight markup language.
HTML
: HyperText Markup Language.複数の用語
複数の連続した用語(コロンのない)が、単一の定義を共有できます。各用語が <dt> になり、定義が <dd> になります。同じ概念に複数の名前や別名があるときに有用です。用語は別々の行に保ちましょう。
CSS
Cascading Style Sheets
: A style sheet language.
JS
JavaScript
: A programming language.
Both terms
: Share one definition.複数の説明
1 つの用語のための複数の連続した定義(各々がコロンで始まる)が、複数の <dd> 要素を作ります。用語のいくつかの異な る意味や側面を列挙するのに有用です。各コロンの行が、独立した定義のエントリです。
Markdown
: A markup language.
: A tool for writing for the web.
Apple
: A fruit.
: A technology company.ネストした定義リスト
ネストした定義リストは、外側の定義の中で、内側のリストを(2〜4 スペース)インデントする必要があります。パーサの対応はまちまちです — ネストを扱えないレンダラもあります。複雑な階層的な用語構造には、信頼性のため HTML の <dl> を検討しましょう。ターゲットのレンダラでテストしてください。
Term
: Definition one.
Nested term
: Nested definition.
: Definition two for top term.ブロック要素付きの定義リスト
定義リストのエントリには、複数の段落、ブロック引用、コードブロックを含められます — 継続するコンテンツは(コロンを超えて)4 スペースでインデントしましょう。内側のコードブロックには合計 8 スペースが要ります。強力ですが脆い部分です。複雑なコンテンツは HTML の <dl> の方が安全です。
Markdown
: A markup language.
With multiple paragraphs in the
definition (indent 4 spaces).
> Blockquote inside definition.
: Second definition with code:
indented code (8 spaces)目次
自動目次
ほとんどのパーサはデフォルトで目次を自動生成しません。一部(toc プラグイン付きの marked、MDX)は [TOC] や {:toc} のプレースホルダーをサポートします。Doctoc や markdown-toc のようなツールが見出しから生成します。静的サイトでは、TOC のコンポーネントがビルド時か実行時に見出しのアンカーを読みます。
## 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 は見出しのテキストから導かれます(小文字、スペースはハイフン、句読点は除去)。見出しの階層を反映するようインデントしましょう。見出しが変わったら手動で更新するか、ジェネレータを使います。
# My Document
## Contents
- [Intro](#intro)
- [Setup](#setup)
- [Prerequisites](#prerequisites)
- [Install](#install)
- [Usage](#usage)
## Intro
...アンカー生成のルール
アンカー生成はパーサにより異なります。よくあるルール:小文字化、スペースはハイフンへ、句読 点の除去、英数字の維持です。GitHub は絵文字といくつかの Unicode を保ちます。数字とドットはしばしば除去されます。確信がなければ、実際の id を見つけるため、描画された HTML を検査しましょう。
## 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 は、見出しのテキストの変化に耐えます。
## 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 を加えましょう。
## Section
Content here.
[Back to top](#table-of-contents)
---
<details>
<summary>Table of Contents</summary>
- [Section 1](#section-1)
- [Section 2](#section-2)
</details>絵文字と特殊文字
絵文字のショートコード
絵文字のショートコード(:name:)が GitHub/GitLab でサポートされています(EmojiOne/Twemoji のセットを使用)。名前付きの絵文字が数千あります。ショートコードは便利ですが移植性がなく — 非 GFM のパーサではリテラルに描画され得ます。最大の互換性のためには、生の Unicode 絵文字を使いましょう。
:smile: :heart: :thumbsup: :rocket:
GFM supports shortcodes:
:sparkles: new feature :tada:
:checkered_flag: launch!
:bug: fixed issue #42よく使う絵文字
ほとんどのモダンなエディタとレンダラが生の Unicode 絵文字を直接扱います — 貼り付けるだけです。ショートコードは GitHub 固有です。絵文字 はトーンとステータスを伝えられます(結果にはチェック/クロス、バグには bug)。正式なドキュメントでは控えめに、README と変更ログでは素晴らしいです。
: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: zapHTML エンティティ
Markdown は HTML へ通すため、HTML エンティティが機能します。リテラルのアンパサンドには(URL/属性では特に)&、角括弧には < >、記号には © ® ™ を使いましょう。数値形式(©)と 16 進(©)が任意の Unicode 文字をカバーします。
& < > " '
© ® ™
— – …
© ©
Use & to show a literal &.特殊文字
Markdown はデフォルトで、プレーンな句読点をタイポグラフィの文字(スマートクォート)に変換しません — HTML エンティティか Unicode の貼り付けを使いましょう。em ダッシュとカーリークォートがタイポグラフィを改善します。これらを自動修正するエディタもあります。矢印と記号には、エンティティが最も明快です。