FAQ

FAQ#

1.  操作指南#

这些部分描述了使用 Sphinx 编写 MyST 的一些常见场景和用例。

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

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

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

Hallo I’m from a Markdown file, with a reference.

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

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

Hallo I'm from an rST file, with a reference.

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

要将 MyST 文件包含在 ReStructuredText 文件中，可以使用 include 指令的 parser 选项：

.. include:: include.md
   :parser: myst_parser.sphinx_

重要

parser 选项需要 docutils>=0.17

1.3.  在 Jupyter Notebooks 中使用 MyST#

MyST-NB 工具提供了 Sphinx 插件，用于解析 使用 MyST Markdown 编写的 Jupyter Notebooks。它包括在文档构建期间自动执行 Notebook、存储 Notebook 单元格输出以便在文档的其他位置插入它们等功能。更多信息请参见 MyST-NB 文档。

1.4.  从文档文件夹外部包含文件（如 README.md）#

参见

将其他文档直接插入当前文档

你可以包含文件，包括来自项目外部的文件，例如：

```{include} ../README.md
```

然而，包含文件通常不会正确解析本地链接，例如 ![](my-image.png)，因为它将文本视为源自“包含文件”。

从 myst-parser 0.12.7 版本开始，添加了新的实验性功能来解决此类链接。你现在可以使用例如：

Source:
```{literalinclude} ../../example.md
:language: md
```
Included:
```{include} ../../example.md
:relative-docs: docs/
:relative-images:
```

Source:

[Used in how-to](docs/faq/index.md)
![alt](docs/_static/logo-wide.svg)

Included:

Used in how-to alt

这里的包含尝试重写本地链接，以便从正确的位置引用它们！ relative-docs 必须给出要重写的任何链接的前缀，以将它们与 sphinx 交叉引用区分开来。

重要

当前功能仅适用于 Markdown 风格的图片和链接。

如果你在使用此功能时遇到任何问题，请随时报告。

1.5.  在 Markdown 文件中使用 sphinx.ext.autodoc#

有关此信息，请参见 记录整个 API。

1.6.  自动为章节标题创建目标#

Added in version 0.13.0: 有关此信息，请参见 隐式目标。

1.7.  抑制警告#

有关此信息，请参见 构建警告。

1.8.  Sphinx 特定的页面前置内容(front matte)#

Sphinx 拦截前置内容并将其存储在全局环境中（如 sphinx 文档 中所述）。某些前置内容键（或其翻译）也被 docutils 特别识别并解析为内联 Markdown：

  • author

  • authors

  • organization

  • address

  • contact

  • version

  • revision

  • status

  • date

  • copyright

  • dedication

  • abstract

经典的用例是指定不在任何 toctree 中的“孤立”文档。例如，在页面顶部插入以下语法将使 Sphinx 将其视为孤立页面：

---
orphan: true
---

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

1.9.  将现有的 rST 迁移到 MyST#

如果你已经有一些 reStructuredText 文件并希望将其转换为 MyST Markdown，可以尝试使用 rst-to-myst 工具，它允许你将单个 rST 文件转换为 MyST Markdown 文档。

2.  禁用解析器的 Markdown 语法#

如果你想启用或禁用自定义 Markdown 语法，请使用 myst_disable_syntax。此列表中的任何内容将不再由 MyST 解析器解析。

例如，要禁用 emphasis 内联语法，请使用以下配置：

myst_disable_syntax = ["emphasis"]

现在将禁用强调语法。例如，以下内容将 不会 渲染为斜体：

*emphasis is now disabled*

有关可以禁用的所有语法元素的列表，请参见 markdown-it 解析器指南。

3.  常见错误和问题#

这些是使用 MyST Sphinx 扩展时人们可能遇到的常见问题和陷阱。

3.1.  在指令中应该使用哪种标记语言？#

如果你需要在另一个内容块 内部 解析内容（例如，note 指令 内部的内容），请注意 MyST 解析器也将用于此嵌套解析。