背景

背景#

这些部分讨论了有关 MyST 生态系统的高层次问题，并解释了项目中的一些决策。

1.  为什么创建 MyST Markdown？#

虽然 Markdown 无处不在，但它不足以用于编写现代、功能齐全的文档。某些 Markdown 变体支持这些功能，但围绕这些功能的各种语法选择没有社区标准。

Sphinx 是用 Python 编写的文档生成框架。它大量使用 reStructuredText 语法，这是另一种用于编写文档的标记语言。特别是，Sphinx 定义了两个非常有用的扩展点：内联角色 和 块级指令。

该项目旨在将 Markdown 的简洁性和可读性与 reStructuredText 和 Sphinx 平台的功能和灵活性结合起来。 它从 [CommonMark Markdown 规范][commonmark] 开始，并选择性地添加了一些额外的语法片段，以利用 reStructuredText 最强大的部分。

备注

CommonMark 社区多年来一直在讨论“官方”扩展语法（例如，参见这个关于指令的七年老帖以及这个最近的对话，以及这个评论列出了更多关于此主题的帖子）。

选择了一种“角色和指令”语法，这似乎是合理的，并且遵循了其他 Markdown 变体中的常见约定。然而，如果 CommonMark 社区决定采用“官方”扩展语法，可能会在 MyST 中使用此语法。

2.  MyST、reStructuredText 和 Sphinx 之间的关系#

MyST Markdown 提供了与 reStructuredText 语法等效的 Markdown 语法，这意味着你可以使用 MyST 完成 reStructuredText 所能完成的所有操作。

Sphinx 文档引擎支持多种不同的输入类型。默认情况下，Sphinx 读取 reStructuredText (.rst) 文件。Sphinx 使用 解析器 将输入文件解析为其自己的内部文档模型（由核心 Python 项目 docutils 提供）。

开发人员可以扩展 Sphinx 以支持其他类型的输入文件。只要有人为该文件编写 解析器，任何内容文件都可以读入 Sphinx 文档结构。一旦内容文件被解析到 Sphinx 中，它的行为几乎与任何其他内容文件相同，无论它是用什么语言编写的。

MyST-parser 是用于 MyST Markdown 语言的 Sphinx 解析器。当你使用它时，Sphinx 将知道如何解析包含 MyST Markdown 的内容文件（默认情况下，Sphinx 会假设任何以 .md 结尾的文件都是用 MyST Markdown 编写的）。一旦文档被解析到 Sphinx 中，无论它是用 rST 还是 MyST Markdown 编写的，它的行为都是相同的。

myst markdown (.md) ------> myst parser ---+
                                           |
                                           +-->Sphinx document (docutils)
                                           |
reStructuredText (.rst) --> rst parser ----+

例如，以下是如何在 MyST Markdown 中编写 toctree 指令：

```{toctree}
My page name <page1>
page2
```

以下是 rST 中的相同内容：

.. toctree::

   My page name <page1>
   page2

它们在 Sphinx 中的行为是相同的。