Markdownリストマスター:CommonMarkおよびGitHub Flavored Markdown (GFM) のインデント規格
Markdownリストレンダリングの技術的基礎
Markdownは、現代のソフトウェアドキュメント、技術仕様書、個人ナレッジベース、およびエンジニア間のコミュニケーションにおける標準的な軽量マークアップ言語として定着しています。単一レベルの箇条書きリスト(- 項目)や番号付きリスト(1. 項目)はシンプルに見えますが、深くネストされた多層構造のドキュメントアウトラインを作成する際には、非常に複雑な整形処理が必要となります。CommonMark、GitHub Flavored Markdown (GFM)、Python-Markdown、Pandocなど、異なるMarkdownパーサーは、リスト記号の選択、タブとスペースの比率、サブロックのインデントに関して厳格かつ繊細なルールを適用します。
VS Code、Sublime Text、Xcode、Apple Notes、Microsoft Wordなどの異なるテキストエディタ間でリストをコピー&ペーストすると、不可視のインデントエラーが発生することがよくあります。ネストされた子要素のスペースが1つ不足しているだけで、Markdownコンパイラはその子ノードを最上位の親要素または独立した段落ブロックとして誤って解釈してしまいます。Utiliomeのネストリスト&インデント整形ツールは、入力テキスト構造のAST(抽象構文木)を解析し、仕様に準拠した標準的なMarkdownを再生成することで、これらのパース異常を完全に排除します。
インデントルール:2スペース vs 4スペースのガイドライン
技術ドキュメント設計において最も頻繁に議論されるテーマの1つが、階層ごとに2スペースと4スペースのどちらでサブリストをインデントすべきかという点です。選択は対象とするMarkdownパーサーの仕様によって異なります。
2スペースインデントルール(標準GFMおよびPrettier): GitHub、Docusaurus、Nextra、Obsidianなどの現代的なWebドキュメントエコシステムでは、インデントレベルあたり2スペースが標準とされています。2スペースの規約では、子要素のコンテンツが親要素のテキスト開始位置にきれいに揃います。
- 親要素 1 - ネストされた子要素 1.1 - ネストされた子要素 1.2 - さらに深くネストされた孫要素 1.2.1 - 親要素 24スペースインデントルール(厳格なCommonMarkおよびPython-Markdown): 厳格なCommonMark実装では、番号付きリスト内部の子ブロック、コードスニペット、およびネストされたリストに対して、親ブロックとの包含関係を保証するために4スペース(またはフル1タブ)のインデントが求められます。
1. ワークフローの最初のステップ - 関連するサブ項目 A - 関連するサブ項目 B 2. ワークフローの第2ステップタブとスペースの混在によるトラブル: 物理的なタブ文字(
\t)とASCIIスペース文字(\x20)の混在は、Markdownドキュメントの表示崩れを引き起こす最大の原因です。Webレンダリングエンジンはタブを不統一に表示するため(4表示列または8表示列など)、ネストされた項目が視覚的に大きくズレてしまいます。Utiliomeは設定に基づいて、すべてのタブ文字を均一なスペース文字列に自動変換します。
箇条書き記号の正規化と連番補正
Markdownでは、無順序リストの記号としてハイフン(-)、アスタリスク(*)、プラス記号(+)の3種類がサポートされています。これらはいずれも有効なHTMLの無順序リスト要素(<ul>)を生成しますが、同一ドキュメント内で記号が混在すると視覚的な散漫さを招き、markdownlint(例:ルールMD004)などの自動リンターチェックでエラーとなります。
また、順序付きリストの番号は編集を重ねるうちに崩れやすくなります。作成者が番号シーケンスの途中に項目を貼り付けたり、自動インクリメントの1.構文に依存したりすることが原因です。
<!-- 未整形・崩れた入力例 -->
* 機能 A
- 機能 B
+ 機能 C
1. 最初のステップ
1. 2番目のステップ(草案からコピー)
4. 順序が崩れたステップ
Utiliomeのフォーマッタは、無順序リストの記号を選択した統一文字(例:すべての項目を-に統一)に正規化し、順序付きシーケンスを正しい連番(1., 2., 3.)またはチームのコードレビューガイドラインに合わせた形式に再構成します。