🚀 开始使用#
本页简要概述了如何开始使用 MyST Markdown,以及如何在 Docutils 和 Sphinx 中使用它。
1. 安装#
要安装 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 包含了 role 和 directive 扩展点,以支持更丰富的功能,例如警告框 和图表。
在你的 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 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 插件列表。