🚀 开始使用#

本页简要概述了如何开始使用 MyST Markdown,以及如何在 Docutils 和 Sphinx 中使用它。

1.  安装#

PyPI Conda

要安装 myst-parser,请使用 pip

pip install myst-parser

或者 Conda:

conda install -c conda-forge myst-parser

2.  编写 Markdown 文档#

首先,创建名为 example.md 的空文件,并为其添加 Markdown 标题和文本。然后,可以使用已安装包中的 myst-docutils-demo 命令行工具 将此文件解析为 HTML:

myst-docutils-demo example.md 
# My nifty title

Some **text**!
<section id="my-nifty-title">
<h1>My nifty title</h1>
<p>Some <strong>text</strong>!</p>
</section>

3.  使用 MyST 语法扩展 Markdown#

MyST 是 CommonMark Markdown 的扩展,它包含了一套丰富的 附加语法 以适用于技术文档编写,并且能够与 Docutils 和 Sphinx 集成。

例如,MyST 包含了 roledirective 扩展点,以支持更丰富的功能,例如警告框图表

在你的 Markdown 页面中添加 admonition 指令和 sup 角色,如下所示:

myst-docutils-demo example.md --myst-enable-extensions=colon_fence
# My nifty title

Some **text**!

:::{admonition} Here's my title
:class: tip

Here's my admonition content.{sup}`1`
:::
<section id="my-nifty-title">
<h1>My nifty title</h1>
<p>Some <strong>text</strong>!</p>
<aside class="admonition tip">
<p class="admonition-title">Here's my title</p>
<p>Here's my admonition content.<sup>1</sup></p>
</aside>
</section>

小技巧

MyST 几乎兼容所有 Docutils 和 Sphinx 的角色和指令。

请注意,Sphinx 提供了 Docutils 角色和指令的超集,因此某些功能可能在 Docutils 命令行工具中无法使用。

4.  交叉引用#

MyST-Parser 提供了强大的 交叉引用功能,链接到文档、标题、图表等。

例如,添加 参考目标 并引用它:

myst-docutils-demo example.md 
(header-label)=
# A header

[My reference](#header-label)
<section id="a-header">
<span id="header-label"></span><h1>A header</h1>
<p><a class="reference internal" href="#header-label">My reference</a></p>
</section>

5.  在 Sphinx 中启用 MyST#

开始使用 Sphinx,请参阅他们的 快速入门指南

要在 Sphinx 中使用 MyST 解析器,只需将以下内容添加到你的conf.py 配置文件 中:

extensions = ["myst_parser"]

这将激活 MyST 解析器插件,使所有扩展名为 .md 的文档都会被解析为 MyST 格式。

现在,example.md 文件可以作为 首页 添加,或者参考 组织内容部分 关于创建 toctree 指令的内容,将 example.md 添加到其中。

小技巧

有许多优秀的 HTML 主题与 MyST 兼容良好,例如sphinx-book-theme(本页面使用的主题)、pydata-sphinx-theme以及 furo

6.  配置 MyST-Parser#

配置 部分包含了 MyST 解析器的完整配置选项列表。

这些配置可以全局应用,例如在 Sphinx 的 conf.py 文件中:

myst_enable_extensions = ["colon_fence"]

或者它们可以应用于特定文档,位于文档顶部的 frontmatter 中:

---
myst:
  enable_extensions: ["colon_fence"]
---

7.  拓展 Sphinx#

另一种在 Sphinx 中扩展 MyST 的方法是安装 Sphinx 插件,以定义新的角色、指令等。

例如,安装 sphinx-design 插件,这将能够创建美观且适应屏幕尺寸的网页组件。

首先,安装 sphinx-design:

pip install sphinx-design

接着,将其添加到你的 conf.py 文件中的插件列表中:

extensions = [
  "myst_parser",
  "sphinx_design",
]

现在,可以使用 design 指令将网页组件添加到我们的 Markdown 文件中!

:::{card} Card Title
Header
^^^
Card content
+++
Footer
:::

Header

Card Title

Card content

::::{tab-set}

:::{tab-item} Label1
Content 1
:::

:::{tab-item} Label2
Content 2
:::

::::

Content 1

Content 2

还有许多其他优秀的 Sphinx 插件与 MyST 兼容,例如本文档中使用的这些插件:

sphinx-design:

为你的文档添加美观且响应式的网页组件

sphinx-copybutton:

为你的代码块添加复制按钮

sphinxext-rediraffe:

为你的文档添加重定向功能

sphinxext-opengraph:

为你的文档添加 OpenGraph 元数据

sphinx-pyscript:

在你的文档中执行 Python 代码,参见此处

sphinx-tippy:

为你的文档添加工具提示,参见此处

sphinx-autodoc2:

从文档字符串生成文档,参见此处

sphinx-togglebutton:

为你的文档添加可折叠内容

sphinxcontrib.mermaid:

生成 Mermaid 图表

参见

sphinx-extensions 是精选且具有明确导向的 Sphinx 插件列表。