内容组织#
Sphinx 允许您将内容组织到多个文档中，并包含来自其他文档的内容。
本节介绍如何使用 MyST Markdown 实现这一点。
1. 文档结构#
单个 MyST Markdown 文档使用 标题 进行结构化。
文档根级别的所有标题都会包含在该页面的目录 (ToC) 中。
许多 HTML 主题已经将目录包含在侧边栏中，但您也可以使用 contents directive 将其包含在页面的主要内容中：
```{contents} Table of Contents
:depth: 3
```
选项：
- depth:
可用于指定目录的深度。
- local:
可用于仅包含文档当前部分的标题。
- backlinks:
可用于在每个部分的末尾包含指向目录的链接。
- class:
可用于向目录添加自定义 CSS 类。
警告
由于文档的结构由标题决定，因此在文档中出现‘非连续’标题是有问题的，例如：
# Heading 1
### Heading 3
如果您希望包含此类标题，可以使用 attrs_block 扩展将标题包裹在 div 中，这样它就不会包含在目录中：
# Heading 1
:::
### Heading 3
:::
在 front-matter 中设置标题
Added in version 0.17.0.
myst_title_to_header = True 配置 允许在 文档 front matter 中存在 title 键。
这将用作文档的标题（解析为 Markdown）。例如：
---
title: My Title with *emphasis*
---
将等同于：
# My Title with *emphasis*
2. 将其他文档直接插入当前文档#
include 指令允许您将另一个文档的内容直接插入到当前文档的流程中。
参见
用于包含文件源代码的 literalinclude 指令。
```{literalinclude} example.txt
```
```{include} example.txt
```
Hallo
there
you!
Hallo there you!
以下选项允许您仅包含文档的一部分：
- start-line:
仅包含从此行号开始的内容（行号从 1 开始，负数表示从末尾倒数）。
- end-line:
仅包含到此行（但不包括该行）为止的内容。
- start-after:
仅包含在首次出现指定文本之后的内容。
- end-before:
仅包含在首次出现指定文本之前（但在任何 after 文本之后）的内容。
```{literalinclude} example.txt
```
```{include} example.txt
:start-line: 1
:end-line: 2
```
```{include} example.txt
:start-after: Hallo
:end-before: you!
```
Hallo
there
you!
there
there
以下选项允许您修改包含文档的内容，使其相对于插入位置进行调整：
- heading-offset:
将所有标题级别偏移此正整数，例如将
#更改为####。- relative-docs:
如果 Markdown 文件引用以特定前缀开头，则使其相对于当前文档。
- relative-images:
使 Markdown 图像引用相对于当前文档。
```{literalinclude} examples/example_relative_include.txt
```
```{include} examples/example_relative_include.txt
:heading-offset: 3
:relative-docs: ..
:relative-images:
```
其他选项：
- encoding:
外部文件的文本编码。
包含到/从 reStructuredText 文件
如 本节 所述，所有 MyST 指令都会将其内容解析为 Markdown。因此，要包含 rST，我们必须首先将指令‘包裹’在 eval-rst 指令 中：
```{eval-rst}
.. include:: ../faq/snippets/include-rst.rst
```
Hallo I'm from an rST file, with a reference.
要在 ReStructuredText 文件中包含 MyST 文件，可以使用 include 指令的 parser 选项：
.. include:: include.md
:parser: myst_parser.sphinx_
重要
parser 选项需要 docutils>=0.17。
3. 使用 toctree 将其他文档作为子文档包含#
为了构建包含多个文档的项目，使用了 toctree 指令。
将指定文档作为当前文档的子文档，从 root_doc 开始构建嵌套的文档层次结构。
```{toctree}
examples/content_child1.md
examples/content_child2.md
```
toctree 选项：
- glob:
表示所有条目将与可用文档列表匹配，并按字母顺序将匹配项插入列表中。
以下选项控制其在文档中的显示方式：
- caption:
此 toctree 的标题。
- hidden:
不在文档中显示。
- includehidden:
包含隐藏的
toctree子条目。- maxdepth:
显示的文档子标题的深度。
- titlesonly:
仅显示第一个顶级标题。
- reversed:
反转列表中条目的顺序。
其他选项：
- name:
允许引用
toctree。- numbered:
为子文档中的所有标题编号。如果指定了整数，则这是编号的深度。
小技巧
子 toctree 会自动编号，因此不要给它们 :numbered: 标志。