🚀 开始使用

🚀 开始使用#

本页简要概述了如何开始使用 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 is an extension of CommonMark Markdown, that includes a rich additional syntax for technical authoring, and can integrate with Docutils and Sphinx.

For example, MyST includes role and directive extensions points, to allow for richer features, such as admonitions and figures.

Lets add an admonition directive and sup role to your Markdown page, like so:

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 works with just about all Docutils and Sphinx roles and directives.

Note, Sphinx provides a superset of the Docutils roles and directives, so some may not work in the Docutils CLI.

4. Cross-referencing#

MyST-Parser offers powerful cross-referencing features, to link to documents, headers, figures and more.

For example, to add a section reference target, and reference it:

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. Enable MyST in Sphinx#

To get started with Sphinx, see their quick-start guide.

To use the MyST parser in Sphinx, simply add the following to your conf.py configuration file:

extensions = ["myst_parser"]

This will activate the MyST Parser extension, causing all documents with the .md extension to be parsed as MyST.

Our example.md file can now be added as the index page, or see the organising content section about creating toctree directives, to add example.md to.

小技巧

There are a range of great HTML themes that work well with MyST, such as sphinx-book-theme (used here), pydata-sphinx-theme and furo

6. Configuring MyST-Parser#

The Configuration section contains a complete list of configuration options for the MyST-Parser.

These can be applied globally, e.g. in the sphinx conf.py:

myst_enable_extensions = ["colon_fence"]

Or they can be applied to specific documents, at the top of the document, in frontmatter:

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

7. Extending Sphinx#

The other way to extend MyST in Sphinx is to install Sphinx extensions that define new roles, directives, etc.

For example, let’s install the sphinx-design extension, which will allow us to create beautiful, screen-size responsive web-components.

First, install sphinx-design:

pip install sphinx-design

Next, add it to your list of extensions in conf.py:

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

Now, we can use the design directive to add a web-component to our Markdown file!

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

Header

Card Title

Card content

Footer

::::{tab-set}

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

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

::::

Label1

Content 1

Label2

Content 2

There are many other great Sphinx extensions that work with MyST, such as the ones used in this documentation:

sphinx-design:: Add beautiful, responsive web-components to your documentation
sphinx-copybutton:: Add a copy button to your code blocks
sphinxext-rediraffe:: Add redirects to your documentation
sphinxext-opengraph:: Add OpenGraph metadata to your documentation
sphinx-pyscript:: Execute Python code in your documentation, see here
sphinx-tippy:: Add tooltips to your documentation, see here
sphinx-autodoc2:: Generate documentation from docstrings, see here
sphinx-togglebutton:: Add collapsible content to your documentation
sphinxcontrib.mermaid:: Generate Mermaid diagrams

参见

sphinx-extensions, for a curated and opinionated list of Sphinx extensions.