在 Sphinx 中开始使用 MyST¶
这个页面描述了如何开始使用 MyST 解析器，重点是在 Sphinx 文档引擎中启用它。
安装 MyST 解析器¶
安装 MyST 解析器可以访问两个工具：
一个 Python 库，可以解析 MyST markdown，并将其呈现为多种输出格式（特别是与 Sphinx 一起使用的
docutils格式）。一个 Sphinx 插件，利用上述工具来解析你的文档中的 MyST Markdown。
要安装 MyST 解析器，请在 Conda 环境 中运行以下内容（推荐）：
conda install -c conda-forge myst-parser
或者
pip install myst-parser
在 Sphinx 启用 MyST¶
Sphinx 是一个文档生成器，用于从多个源文档和 assets 中建立网站或书籍。要开始使用 Sphinx，请看他们的 快速入门指南。本指南假设你已经有了一个预先存在的 Sphinx 网站，并能正常构建。
要在 Sphinx 中使用 MyST 解析器，只需在你的 conf.py 文件中加入以下内容：
extensions = ["myst_parser"]
这将激活 MyST 解析器插件，使所有以 .md 为扩展名的文件被解析为 MyST。
你可以同时使用 MyST 和 reStructuredText
激活 MyST 解析器将简单地 enable 用 MyST 解析 markdown 文件，而 Sphinx 中的 rST 解析器仍将以同样的方式工作。以 .md 结尾的文件将被解析为 MyST，而以 .rst 结尾的文件将被解析为 reStructuredText。
编写你的第一份 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！
用指令来扩展 markdown¶
MyST markdown最重要的功能是编写 指令。指令有点像函数，是为编写内容而设计的。Sphinx 和 reStructuredText 广泛地使用指令。下面是一个指令在 MyST markdown 中的样子：
```{directivename} <directive arguments>
:optionname: <valuename>
<directive content>
```
对于那些熟悉 reStructuredText 的人来说，你可以在这里找到 从 MyST 指令语法到 rST 语法的映射。
如上所述，在撰写指令时，有四个主要部分需要考虑。
the directive name 有点像函数名称。不同的名称触发不同的功能。它们被包裹在
{}括号中。directive arguments 就在指令名称后面。它们可以用来触发指令中的行为。
directive options 就在指令的第一行之后。它们也控制指令的行为。
directive content 是你放在指令里面的 markdown。指令经常以一种特殊的方式显示内容。
例如，在你的 markdown 页面添加一个 admonition 指令，像这样：
# My nifty title
Some **text**!
```{admonition} Here's my title
:class: warning
Here's my admonition content
```
重新建立你的斯芬克斯网站，你应该看到新的告诫框出现了。
正如你所看到的，我们已经使用了上面描述的四个部分中的每一个来配置这个指令。下面是该指令在渲染时的样子：
Here’s my title
Here’s my admonition content
参见
关于在 MyST 中使用指令的更多信息，见 Directives - a block-level extension point。
用一个角色引用一个章节的标签¶
角色是另一个核心的 Sphinx 工具。他们的行为类似于指令，但与文本连在一起，而不是在一个单独的块中。它们有以下形式：
{rolename}`role content`
角色比指令更简单一些，尽管有些角色允许在其内容区域内使用更复杂的语法。例如，ref 角色用于对你的文档的其他部分进行引用，并允许你在角色中指定显示的文本和引用本身：
{ref}`My displayed text <my-ref>`
例如，让我们在你的 markdown 文件中添加一个节引用。要做到这一点，我们首先需要在你的页面的某个部分添加一个 标签。要做到这一点，请使用以下结构：
(label-name)=
## Some header
把这个添加到你上面的 markdown 文件中，像这样：
# My nifty title
Some **text**!
```{admonition} Here's my title
:class: warning
Here's my admonition content
```
(section-two)=
## Here's another section
And some more content.
因为你的新章节有一个标签（section-two），你可以用 ref 角色引用它。像这样把它添加到你的 markdown 文件中：
(label-name)=
## Some header
把这个添加到你上面的 markdown 文件中，像这样：
# My nifty title
Some **text**!
```{admonition} Here's my title
:class: warning
Here's my admonition content
```
(section-two)=
## Here's another section
And some more content.
And here's {ref}`a reference to this section <section-two>`.
I can also reference the section {ref}`section-two` without specifying my title.
重新构建你的文档，你应该看到引用被自动插入。下面是一个例子，说明 ref 角色在最终输出中的样子：
这里有一个 用一个角色引用一个章节的标签 的引用。
参见
关于角色的更多信息，见 Roles - an in-line extension point。
使用额外的 MyST 语法添加注释¶
MyST 中还有许多其他种类的语法，使写作更有成效，更有乐趣。让我们来玩一玩几个选项。
首先，试着写一个 注释。这可以通过在你的 markdown 文件中添加一个以 % 开头的行来完成。例如，试着在你的 markdown 文件中添加一个注释，像这样：
# My nifty title
Some **text**!
```{admonition} Here's my title
:class: warning
Here's my admonition content
```
(section-two)=
## Here's another section
And some more content.
% This comment won't make it into the outputs!
And here's {ref}`a reference to this section <section-two>`.
I can also reference the section {ref}`section-two` without specifying my title.
重新构建你的文档 – 注释不会出现在输出中。
通过配置扩展 MyST¶
到目前为止，我们已经涵盖了 MyST 的基本语法与 Sphinx。然而，有几种方法可以扩展这个基本语法并获得新功能。首先是在 MyST 解析器中启用一些 “out of the box” 的插件。这些添加的新语法不是 “核心MyST” 的一部分，但仍然是有用的（并且有一天可能成为核心 MyST 的一部分）
让我们扩展 MyST 的基本语法，以实现 指令的栅栏。这允许你除了用 ```，之外，可以用 ::: 来定义指令。这对内容中含有标记的指令很有用。通过使用 :::，非 MyST 的 markdown 渲染器仍然能够渲染里面的内容（而不是显示为代码块）。
要激活扩展，在你的 conf.py 文件中添加一个列表，其中包含你想激活的扩展。例如，要激活 “colon code fences” 扩展，请在你的 conf.py 文件中添加以下内容：
myst_enable_extensions = [
"colon_fence",
]
你现在可以使用 ::: 来定义指令。例如，像这样修改你的 markdown 文件：
# My nifty title
Some **text**!
```{admonition} Here's my title
:class: warning
Here's my admonition content
```
(section-two)=
## Here's another section
And some more content.
% This comment won't make it into the outputs!
And here's {ref}`a reference to this section <section-two>`.
I can also reference the section {ref}`section-two` without specifying my title.
:::{note}
And here's a note with a colon fence!
:::
当你建立你的网站时，它应该在你的输出中呈现为一个 “note block”。
安装一个新的 Sphinx 插件并使用其功能¶
另一种在 Sphinx 扩展 MyST 的方法是 Sphinx 插件，定义新的指令。指令有点像 Sphinx 中的 “functions”，安装一个新的包可以添加新的指令在你的内容中使用。
例如，让我们安装 sphinxcontib.mermaid 插件，这将允许我们用 MyST 生成 Mermaid 图。
首先，安装 sphinxcontrib.mermaid：
pip install sphinxcontrib-mermaid
接下来，在 conf.py 中把它添加到你的插件列表中：
extensions = [
"myst_parser",
"sphinxcontrib.mermaid",
]
现在，在你的 markdown 文件中添加一个 mermaid 指令。比如说：
# My nifty title
Some **text**!
```{admonition} Here's my title
:class: warning
Here's my admonition content
```
(section-two)=
## Here's another section
And some more content.
% This comment won't make it into the outputs!
And here's {ref}`a reference to this section <section-two>`.
I can also reference the section {ref}`section-two` without specifying my title.
:::{note}
And here's a note with a colon fence!
:::
And finally, here's a cool mermaid diagram!
```{mermaid}
sequenceDiagram
participant Alice
participant Bob
Alice->John: Hello John, how are you?
loop Healthcheck
John->John: Fight against hypochondria
end
Note right of John: Rational thoughts <br/>prevail...
John-->Alice: Great!
John->Bob: How about you?
Bob-->John: Jolly good!
```
当你建立你的文档时，你应该看到像这样的东西：
接下来的步骤 - 了解更多关于 MyST 语法的信息¶
在本教程中，我们介绍了 MyST Markdown 的一些基础知识，如何在 Sphinx 中启用和使用它，以及如何为新的使用场景扩展它。MyST（以及 Sphinx 生态系统）还有更多的功能，我们在这里没有涉及。更多信息，请看 MyST 语法文档 和 关于使用 MyST 与 Sphinx 的文档。