環境
- Python 3.12.1
- sphinx 7.4.7
- pydata-sphinx-theme 0.15.4
はじめに
Markdownでは、ネストされた箇条書きは以下のように書けます。
* A
* B
* C
* X
* Y
* D
下図は、Visual Studio CodeのMarkdown拡張で表示した結果です。
これをreStructuredTextで表現しようとしたらハマったので、いろいろ検証しました。
箇条書きの下に箇条書き
Markdownと同じ内容の場合
上記のテキストをreStructuredTextとしてsphinxでビルドしたら、以下のHTMLが出力されました。
ネストされていますが、HTMLのdtタグによってCだけ太字になっていました。
<ul class="simple">
<li><p>A</p></li>
<li><p>B</p></li>
<li><dl class="simple">
<dt>C</dt><dd><ul>
<li><p>X</p></li>
<li><p>Y</p></li>
</ul>
</dd>
</dl>
</li>
<li><p>D</p></li>
</ul>
reStructuredTextのDefinition listとしてみなされているようです。
ネストされている部分に空行を入れる
公式ドキュメントには、
ネストされたリストも使用できますが、親のリストとは空白行で区切る必要があります:
とあるので、空行を入れてみました。
* A
* B
* C
* X
* Y
* D
X,Yはネストされずに、引用された形式になりました。
<ul>
<li><p>A</p></li>
<li><p>B</p></li>
<li><p>C</p>
<blockquote>
<div><ul class="simple">
<li><p>X</p></li>
<li><p>Y</p></li>
</ul>
</div></blockquote>
</li>
<li><p>D</p></li>
</ul>
Sphinxのドキュメントには、
前の段落より１段インデントが深い段落は引用になります。:
と書いてあったので、インデントが「引用」とみなされたようです。
インデントを空白4文字から空白2文字にする
空白を入れずに、インデントを空白4文字から空白2文字にしました。
* A
* B
* C
* X
* Y
* D
XとYは箇条書きとみなされませんでした。
<ul class="simple">
<li><p>A</p></li>
<li><p>B</p></li>
<li><p>C
* X
* Y</p></li>
<li><p>D</p></li>
</ul>
空行を入れて、インデントを空白4文字から空白2文字にする
* A
* B
* C
* X
* Y
* D
期待通り、XとYはネストされました。
<ul class="simple">
<li><p>A</p></li>
<li><p>B</p></li>
<li><p>C</p>
<ul>
<li><p>X</p></li>
<li><p>Y</p></li>
</ul>
</li>
<li><p>D</p></li>
</ul>
番号付き箇条書きの下に箇条書き
空行を入れて、インデントを空白2文字
番号付き箇条書きの場合、数字でなくピリオドからインデントを数えています。したがって、行頭と* Xの間の空白は３文字です。
1. A
2. B
* X
* Y
3. D
<ol class="arabic simple">
<li><p>A</p></li>
<li><p>B</p>
<ul class="simple">
<li><p>X</p></li>
<li><p>Y</p></li>
</ul>
</li>
<li><p>D</p></li>
</ol>
まとめ
reStructuredTextでネストされた箇条書きを書く場合は、ネストされている箇条書きの上下に空行を入れて、インデントは空白2文字にします。