Get started with MyST in Sphinx

5.2. Get started with MyST in Sphinx#

本页面描述了如何开始使用MyST解析器，重点介绍如何在Sphinx文档引擎中启用它。

5.2.1. 安装MyST解析器#

安装 MyST 解析器可以访问两个工具：

  • 一个 Python 库，可以解析 MyST Markdown，并将其呈现为多种输出格式（特别是docutils与 Sphinx 一起使用的格式）。

  • 一个 Sphinx 扩展，它利用上述工具来解析文档中的 MyST Markdown。

要安装 MyST 解析器，请在Conda 环境中运行以下命令 （推荐）：

conda install -c conda-forge myst-parser

或者

pip install myst-parser

5.2.2. 在 Sphinx 中启用 MyST#

要在 Sphinx 中使用 MyST 解析器，只需将以下内容添加到您的conf.py文件中：

extensions = ["myst_parser"]

这将激活 MyST Parser 扩展，导致所有带有该.md扩展的文档都被解析为 MyST。

能够同时使用 MyST 和 reStructuredText

激活MyST解析器只会使用MyST解析markdown文件，而Sphinx附带的rST解析器仍然会以相同的方式工作。以.md结尾的文件将被解析为MyST，而以.rst结尾的文件将被解析为reStructuredText。

5.2.3. 编写你的第一个 Markdown 文档#

如果现在您已经在 Sphinx 中启用了 myst-parser ，您可以在一个 .md 扩展名结尾的文件中编写 MyST Markdown 。

备注

MyST Markdown 是两种 Markdown 风格的混合体：

它在其基础上支持 CommonMark Markdown 的所有语法。这是许多项目中使用的社区标准的 Markdown 风格。

此外，它还包括对 CommonMark 的几个扩展。这些为技术写作添加了额外的语法特性，例如 Sphinx 使用的角色和指令。

首先，创建一个名为的空文件 myfile.md 并给它一个 Markdown 标题和文本。

# My nifty title

Some **text**!

在您的 Sphinx 项目的“主文档”（您的 Sphinx 文档的登录页面）中，包含myfile.md一个toctree指令，以便将其包含在您的文档中：

.. toctree::

   myfile.md

现在建立你的网站：

make html

并导航到您的登录页面。您应该会看到一个指向从 生成的页面的链接myfile.md。单击该链接应将您带到呈现的 Markdown！

5.2.4. 使用指令扩展 markdown#

通过了解 CommonMark Markdown ，我们可以知道社区标准的 Markdown 风格的语法和实现的功能十分少，不能编写复杂的文档。

MyST Markdown 最重要的功能是编写指令。指令有点像为编写内容而设计的函数。Sphinx 和 reStructuredText 广泛使用指令。以下是指令在 MyST markdown 中的外观：

```{directivename} <directive arguments>
:optionname: <valuename>

<directive content>
```

如上所述，编写指令时需要考虑四个主要部分。

  • 指令名称有点像函数名称。不同的名称触发不同的功能。它们用{}括号括起来。

  • 指令参数紧跟在指令名称之后。它们可用于触发指令中的行为。

  • 指令选项紧跟在指令的第一行之后。它们还控制指令的行为。

  • 指令内容是您放在指令中的 Markdown 标识 。MyST 将指令内容解析为 Markdown。这意味着 MyST markdown 可以写在任何用 MyST markdown 编写的指令的内容区域中。

目录