Markdown のインデント：入れ子のリスト、段落、コード
入れ子の箇条書き、番号付きリスト、続きの段落、フェンス付きコードの例で Markdown のインデントを修正し、意図しないコードブロックを防ぎます。
Markdown のサブリストをインデントするには、親項目の本文の最初の文字の下にマーカーをそろえます。- 親項目 ならスペース 2 個、1. 親項目 なら 3 個です。インデントは文書構造を制御するため、通常の段落にスペースを追加することは、Word で段落の見た目のインデントを変えることとは大きく異なる結果になる場合があります。
まず Markdown ビューアーでこの例を試してください。
- プロジェクト文書
- インストールガイド
- リリースノート
- レビューチェックリスト
インストールガイドとリリースノートは、プロジェクト文書の項目の下に表示されるはずです。レビューチェックリストは外側の階層に残ります。
親項目の本文の位置から数える
マーカーの後にスペースを 1 個置く通常のリスト項目では、次の表に従って位置をそろえます。
| 親項目の書き出し | 本文の前の文字数 | サブリストのインデント |
|---|---|---|
- | 2 | スペース 2 個 |
1. | 3 | スペース 3 個 |
12. | 4 | スペース 4 個 |
100. | 5 | スペース 5 個 |
このため、「常にスペース 2 個」といった一律のルールは番号付きリストには通用しません。GitHub の入れ子のリストのドキュメントでは、桁数の多い番号のマーカーも含め、親項目の本文を基準に位置をそろえる方法が示されています。
1. リリースを準備する
- バージョン番号を確認する。
- 変更履歴を更新する。
2. ドキュメントを公開する
入れ子のマーカーの前にはスペースが 3 個あります。これらを左端から書くと、最初の番号付きの手順には属さず、別のリストを開始します。
古い Markdown 処理系を使う場合は、その処理系でもファイルをプレビューしてください。ここでの例は CommonMark 形式の解析と GitHub Markdown を対象としています。古い実装では入れ子のブロックの認識方法が異なる場合があります。
リスト項目の中に段落を追加する
長い説明に独自の箇条書き記号は必要ありません。空行を入れ、新しい段落を項目の本文の下にそろえます。
1. インストールガイドをレビューする。
初めて読む人が、内部文書を開かずに
セットアップを完了できることを確認します。
2. リリースノートを承認する。
説明の段落は手順 1 に属します。明示的な改行を加えない限り、ソースの 2 行は続けて表示されます。
3 個のスペースを省くと、番号付きリストが終了し、説明が通常の段落になることがあります。編集の流れによっては、その後のリストの番号が最初から振り直される原因にもなります。
箇条書きでも同じ形を使えます。
- インストールガイド
前提条件、セットアップのコマンド、検証手順を含めます。
- リリースノート
説明が複数の文で構成される場合は、別の段落を使います。読者が個別に目を通すべき独立した項目が並ぶ場合は、サブリストを使います。
番号付きの手順の中にコードを置く
フェンス付きコードなら、コマンド例の境界が明確になります。開始フェンス、内容、終了フェンスをすべてインデントし、ブロックをリスト項目内に収めます。
1. インストール済みのバージョンを確認する。
```sh
node --version
```
結果をレビューメモに記録します。
2. プロジェクトのチェックを実行する。
この例では、フェンスは インストール済み の最初の文字の下から始まります。フェンスの後の段落も同じ位置にそろえているため、最初の手順の中に残ります。
次の番号付き手順がコードブロックの一部になる場合は、終了フェンスを確認してください。コードがリストの外に出る場合は、フェンスの前のスペースを確認します。言語ラベルやバッククォートを文字として記述する方法は、コードブロックガイドをご覧ください。
スペース 4 個で文章がコードになる理由
文書の最も外側の階層では、空行の後に行頭へスペースを 4 個置くと、インデントによるコードブロックを作れます。
通常の段落です。
この行はコードとして表示されます。
これは意図された Markdown の構文であり、インデント機能の故障ではありません。CommonMark のインデントによるコードブロックのリファレンスでは、インデントとブロックの境界の役割が説明されています。
通常の段落の直後に続くインデント行には、異なる解析上の制約があります。そのため、スペースを挿入して段落の見た目を字下げする方法は確実ではありません。リスト内では、必要なスペースの数は、それを含む項目との相対関係でも決まります。
引用には引用ブロックを使ってください。最終的なレポートで通常の文章の先頭行を字下げしたい場合は、Markdown では普通の段落にしておき、書き出した後に Word で段落の書式を設定します。こうすれば、内容の意図した意味を保てます。
問題の調査ではスペースを優先する
タブは表示上の複数列を占め、エディターによって幅が異なることがあります。ソースではリストがそろっているのに正しく表示されない場合は、エディターで空白文字を表示し、行頭のタブを必要な数のスペースに置き換えてください。
コード例の中のタブまで一律に置き換えないでください。そこでは空白が例そのものの一部である可能性があります。修正は、周囲のリスト構造を決める Markdown マーカーと続きの内容のインデントに限定します。
改行しないスペースのエンティティを繰り返して、入れ子のリストをまねるのは避けてください。あるプレビューでは文字がずれて見えても、元の文書は互いに関係のない段落のままかもしれません。
Word に書き出す前に構造を検証する
親項目、サブリスト、2 つ目の段落、フェンス付きコードブロックを含む代表的な節を 1 つ確認します。Markdown から HTML への変換ツールでは、本当の入れ子のリストは親のリスト項目の中に含まれます。見た目のずれだけでは、この関係は成立しません。
次に Markdown から Word への変換ツールを使い、DOCX を開きます。番号が意図どおり続いていることと、コマンドが対応する手順に属していることを確認してください。Word のリストスタイルはブラウザーと異なる見た目の間隔を使うことがあるため、共有する前に階層と最終文書の外観の両方を確認しましょう。