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

Question

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

我的index.rst文件中有

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

   documents/Markdown

在Markdown.md中，我有

# Markdown

## H2 Heading

渲染主页面时，我会在toctree中出现H2标题。

我在toctree的其他部分中希望：maxdepth大于1。为什么狮身人面像为什么将H2标题作为toctree的一部分读取，以及如何才能停止它而不必进行设置？ ：maxdepth到1？

Answer 1

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

如果您使用:maxdepth: 1，则“ H2标题”应该消失。

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;
}