MyST Markdown 概述#
除了 Jupyter Notebook Markdown，Jupyter Book 还支持一种特殊的 Markdown 风格，称为 MyST（或 Markedly Structured Text）。它旨在使使用 Markdown 符号编写可发布的计算文档变得更加容易。它是 CommonMark Markdown 的超集，并深受 RStudio 的 RMarkdown 语言 的启发。
无论你是用 Jupyter 笔记本（.ipynb）还是普通 Markdown 文件（.md）编写书籍内容，你都将使用相同的 MyST Markdown 风格。Jupyter Book 将知道如何解析这两者。
本页包含了一些关于 MyST Markdown 及其与 Jupyter Book 关系的介绍。你可以在 Myst Parser 文档 中找到更多关于这种 Markdown 风格的信息。
想直接使用 RMarkdown 吗？
指令和角色#
角色和指令是 Jupyter Book 中最强大的工具之一。它们有点像 函数，但用标记语言编写。它们都服务于类似的目的，但 角色在一行中编写，而 指令跨越多行。它们都接受不同类型的输入，它们如何处理这些输入取决于所使用的具体角色或指令。
指令#
指令定制书籍的外观、感觉和行为。它们有点像 函数，并且有多种名称和不同的行为。本节介绍如何结构化和使用它们。
最简单的情况下，你可以在书中使用指令，如下所示：
```{mydirectivename}
我的指令内容
```
这只有在存在名为 mydirectivename 的指令时才会生效（目前不存在）。Jupyter Book 附带了许多预定义的指令。例如，要在内容中插入一个注释框，你可以使用以下指令：
```{note}
这里是一个注释
```
这将在你构建的书中插入：
Note
这里是一个注释
有关使用指令的更多信息，请参阅 MyST 文档。
指令中的更多参数和元数据#
许多指令允许你使用额外的信息来控制它们的行为。除了指令名称和指令内容外，指令还允许另外两个配置点：
指令参数 - 紧随 {directivename} 之后的一组单词。
以下是指令参数的示例用法：
```{directivename} arg1 arg2
我的指令内容。
```
指令关键字 - 一组标志或键/值对，紧随 {directivename} 之下。
有两种写指令关键字的方式，要么使用 :key: val 对，要么使用 --- 行包围的 key: val 对。它们的工作方式相同：
以下是使用 :key: val 语法的指令关键字示例：
```{directivename}
:key1: metadata1
:key2: metadata2
我的指令内容。
```
以下是使用 --- 语法的指令关键字示例：
```{directivename}
---
metadata1: metadata2
metadata3: metadata4
---
我的指令内容。
```
Tip
记住，使用 :key: 或 --- 指定指令关键字不会有任何区别。我们建议使用 --- 如果你有很多关键字需要指定，或者如果某些值将跨越多行。使用 :key: val 语法作为仅指定一两个关键字的简写。
有关如何使用这些的示例，请参见下面的章节。
角色#
角色与指令非常相似，但它们更简单，并且完全在一行中编写。你可以在书中使用角色，语法如下：
一些内容 {rolename}`这里是我的角色的内容！`
同样，只有在 rolename 是有效的角色名称时，角色才会生效。例如，doc 角色可以用来引用书中的另一页。你可以通过相对路径直接引用另一页。例如，语法 {doc}`../intro` 将产生：使用Jupyter Book构建。
Warning
角色目前要求在源文件中同一行。如果跨越多行，将无法正确解析。有关支持跨越多行的角色的进展，可以跟踪 此问题
有关使用角色的更多信息，请参阅 MyST 文档。
有哪些可用的角色和指令？#
目前没有一份单一的角色/指令列表可供参考，但本节尽可能提供详细信息。对于熟悉Sphinx生态系统的人来说，你可以使用Sphinx中可用的任何指令/角色。这是因为Jupyter Book使用Sphinx来构建你的书籍，而MyST Markdown支持Sphinx支持的所有语法（可以将其视为reStructuredText的Markdown版本）。
Caution
如果你在互联网上（以及以下链接）搜索关于角色和指令的信息，文档通常是以reStructuredText为前提编写的。MyST Markdown与reStructuredText不同，但所有功能应该相同。有关MyST与rST之间差异的更多信息，请参阅MyST Sphinx解析器文档。
要查看可用的指令列表，有三个地方可以检查：
Sphinx指令页面列出了Sphinx中默认可用的指令。
reStructuredText指令页面列出了Python“docutils”模块中的指令。
本文档中还有几个特定于Jupyter Book的附加指令。
如果在rST中存在但在MyST中不存在怎么办？
在某些不常见的情况下，MyST可能与某个角色或指令不兼容。在这种情况下，你可以使用特殊的eval-rst指令直接解析reStructuredText：
```{eval-rst}
.. note::
用reStructuredText编写的注释。
```
这将生成
Note
用reStructuredText编写的注释。
See also
有关指令如何解析内容的MyST-Parser文档，以及如何用于在Markdown文件中包含rST文件，以及如何在Markdown文件中使用sphinx.ext.autodoc。
在Markdown中嵌套内容块#
如果你想在Markdown中嵌套内容块（例如，将{note}放入{margin}中），可以通过在外层块添加额外的反引号（`）来实现。这对代码块也同样适用。
例如，以下语法：
````
```
```
````
生成
```
```
因此，如果你想嵌套指令，可以采用相同的方法。例如，以下语法：
````{margin}
```{note}
这是我的注释！
```
````
生成：
其他MyST Markdown语法#
除了角色和指令外，MyST Markdown还支持多种其他类型的语法。MyST支持所有CommonMark Markdown语法（Jupyter笔记本使用的Markdown类型），以及用于科学出版的扩展语法。
MyST-Parser是Jupyter Book用于允许你使用MyST编写书籍内容的工具。它也是了解MyST语法的一个很好的信息来源。以下是一些可以作为参考的链接：
See also
有关启用扩展MyST语法的信息，请参阅content-blocks:myst-extensions。此外，请参阅本文档中其他示例，了解此扩展语法（以及如何启用每个语法）。
我能用MyST Markdown创建什么？#
请参阅特殊内容块，了解在Jupyter Book中使用MyST Markdown可以做什么的介绍。此外，本网站的其他页面还涵盖了如何使用MyST指令的许多更多用例。
用于编写MyST Markdown的工具#
社区中有一些工具支持MyST Markdown。这里我们列出了一些突出的工具。
Jupyter界面#
虽然MyST Markdown（尚）不能在传统的Jupyter界面中渲染，但其语法应该能够“优雅地降级”，这意味着你仍然可以在Jupyter中使用MyST，然后使用Jupyter Book构建你的书籍。
Jupytext和文本同步#
对于处理Jupyter笔记本和Markdown文件，我们推荐jupytext，这是一个开源工具，用于在.ipynb和文本文件之间进行双向转换。Jupytext支持MyST Markdown格式。
如果使用VS Code编辑Markdown文件， VS Code MyST Markdown扩展 提供了语法高亮和其他功能。