MyST 与 Sphinx

5.5. MyST 与 Sphinx#

MyST 解析器与 Sphinx 扩展捆绑在一起，允许您完全在 MyST 中（或在 rST 和 MyST 的组合中）使用编写 Sphinx 文档。 以下部分介绍了 Sphinx 扩展的一些主要功能。 这些部分描述了使用 Sphinx 编写 MyST 的一些常见场景和用例。

5.5.1. 将 rST 文件包含到 Markdown 文件中#

如本节所述，所有 MyST 指令都将其内容解析为 Markdown。因此，使用常规 include 指令，将文件内容解析为 Markdown：

```{include} ./include-md.txt
```

This is from markdown file.

要包含 rST，我们必须首先将指令“包装”在 eval-rst 指令中：

```{eval-rst}
.. include:: ./include-rst.txt
```

From rst file.

5.5.2. 将 Markdown 文件包含到 rST 文件中#

要在 ReStructuredText 文件中包含 MyST 文件，我们可以使用 include 指令并指定 parser 选项：

.. include:: include-md.txt
   :parser: myst_parser.sphinx_

5.5.3. 在 Jupyter Notebooks 中使用 MyST#

MyST-NB 工具提供了一个Sphinx扩展，用于解析使用 MyST Markdown 写的 Jupyter Notebooks。 它包括在文档构建期间自动执行笔记本、存储笔记本单元输出以便将它们插入文档的其他地方等功能。 有关更多信息，请参阅MyST-NB文档。

5.5.4. 自动为节标题创建目标#

在使用交叉引用时需要为目标创建锚点，在Sphinx中缺省需要手工创建。 为了简化使用，可以使用 Sphinx 扩展 autosectionlabel 来自动创建。 这个扩展需要安装与在 conf.py 中配置。

5.5.5. Sphinx 特殊指令#

一个经典的用例是指定“孤立”文档，这些文档未在任何目录树中指定。 在 Sphinx 中构建时如果存在“孤立”文档会给出警告信息。 为了避免生产这种信息，可以在页面顶部插入以下声明其为孤立页面。

---
orphan: true
---

This is an orphan document, not specified in any toctrees.
目录