Sphinx 将 Markdown 文件中的标题添加到文档结构中

Question

我已将 Sphinx 配置为使用降价文件。

在我的 index.rst 文件中我有

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   documents/Markdown

在 Markdown.md 我有

# Markdown

## H2 Heading

当我呈现主页时，我在 toctree 中看到了 H2 标题。

我的 toctree 的其他部分需要 :maxdepth 大于 1。为什么 sphinx 读取 H2 标题作为 toctree 的一部分，我怎样才能让它停止这样做，而不必将 :maxdepth 设置为 1?

Answer 1

maxdepth 选项表示目录的所需深度。

如果你使用:maxdepth: 1，"H2 heading"应该消失。

Answer 2

@mzjn 部分回答了您的请求。就个人而言，我不确定这在 Markdown 中是如何完成的，但我认为它类似于 reStructuredText。不幸的是，目前没有一种直观的方法可以做到这一点。但是，您可以执行以下操作：

.. toctree::
   :maxdepth: 1

   documents/Markdown1

.. toctree::
   :maxdepth: 2

   documents/Markdown2

这将输出所需的行为，但在这种情况下，两棵树之间会有一些垂直间距。要么你这样做，要么你可以使用：

.. toctree::
   :maxdepth: 2

   documents/Markdown1
   documents/Markdown2

但是你需要将你不想显示的内容转移到较低的级别（例如H3）。

Answer 3

补充@SuperKogito 的回答。如果您希望您的 TOC 支持不同的深度级别，同时仍然看起来完整，您可以通过 CSS.

来实现

例如，给定以下部分

Contents  # this will create a <div id="contents>...</>
========

.. toctree::
   :maxdepth: 1

   documents/Markdown1

.. toctree::
   :maxdepth: 2

   documents/Markdown2

在您的 conf.py 底部，添加以下行

def setup(app):
    app.add_css_file('styles.css')

现在，在您的 _static 文件夹（与您的 conf.py 处于同一文件夹级别）中，添加一个名为 styles.css 的文件，其中包含以下行

// this selects the contents section, the first table of contents and the list item
// underneath it. Then it removes the spacing to make it look whole. If you have more
// items, you can consider using :not(:last-of-type) selector. 
#contents .toctree-wrapper:first-of-type ul {
    margin-bottom: 0;
}

Sphinx 将 Markdown 文件中的标题添加到文档结构中

Sphinx adds Headings from Markdown File to Document Structure

markdown

python-sphinx

commonmark

toctree