1. Get started with MyST in Sphinx¶
本页面描述了如何开始使用MyST解析器，重点介绍如何在Sphinx文档引擎中启用它。
1.1. 安装MyST解析器¶
安装 MyST 解析器可以访问两个工具：
一个 Python 库，可以解析 MyST Markdown，并将其呈现为多种输出格式（特别是
docutils与 Sphinx 一起使用的格式）。一个 Sphinx 扩展，它利用上述工具来解析文档中的 MyST Markdown。
要安装 MyST 解析器，请在Conda 环境中运行以下命令 （推荐）：
conda install -c conda-forge myst-parser
或者
pip install myst-parser
1.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。
1.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！
1.4. 使用指令扩展 markdown¶
通过了解 CommonMark Markdown ，我们可以知道社区标准的 Markdown 风格的语法和实现的功能十分少，不能编写复杂的文档。
MyST Markdown 最重要的功能是编写指令。指令有点像为编写内容而设计的函数。Sphinx 和 reStructuredText 广泛使用指令。以下是指令在 MyST markdown 中的外观：
```{directivename} <directive arguments>
:optionname: <valuename>
<directive content>
```
如上所述，编写指令时需要考虑四个主要部分。
指令名称有点像函数名称。不同的名称触发不同的功能。它们用{}括号括起来。
指令参数紧跟在指令名称之后。它们可用于触发指令中的行为。
指令选项紧跟在指令的第一行之后。它们还控制指令的行为。
指令内容是您放在指令中的降价。MyST 将指令内容解析为 Markdown。这意味着 MyST markdown 可以写在任何用 MyST markdown 编写的指令的内容区域中。