Sphinx将Markdown文件中的标题添加到文档结构中 [英] Sphinx adds Headings from Markdown File to Document Structure

问题描述

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

I have configured Sphinx to use markdown files.

我的index.rst文件中有

In my index.rst file I have

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

   documents/Markdown

在Markdown.md中，我有

In Markdown.md I have

# Markdown

## H2 Heading

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

When I render the main page I get the H2 heading appearing in the toctree.

我在toctree的其他部分中希望:maxdepth大于1.为什么狮身人面像将H2标题作为toctree的一部分读取，以及如何获取它以停止这样做，而不必设置:maxdepth到1?

I have other parts of my toctree where I want a :maxdepth of more than 1. Why does sphinx read the H2 heading as part of the toctree, and how can I get it to stop doing this, without having to set the the :maxdepth to 1?

推荐答案

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

@mzjn answers partially your request. Personally, I am not sure how is this exactly done in Markdown but I assume it is similar to reStructuredText. Unfortunately, at the moment there isn't an intuitive way to do this. However, you can do the following:

.. toctree::
   :maxdepth: 1

   documents/Markdown1

.. toctree::
   :maxdepth: 2

   documents/Markdown2

这将输出所需的行为，但是在这种情况下，您的两棵树之间会有一定的垂直间距.您可以这样做，也可以使用:

This will output the desired behaviour but you will have some vertical spacing between your two trees in this case. Either you do that or you can use:

.. toctree::
   :maxdepth: 2

   documents/Markdown1
   documents/Markdown2

但是您需要将您不想显示的内容转移到较低的级别(例如H3).

But you will need to transfer what you don't want to be shown to a lower level (H3 for example).

这篇关于Sphinx将Markdown文件中的标题添加到文档结构中的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！