π Get Started#
This page gives a quick overview of how to get started with MyST Markdown, and how to use it within Docutils and Sphinx.
1. Installation#
To install myst-parser use pip:
pip install myst-parser
or Conda:
conda install -c conda-forge myst-parser
2. Write a Markdown document#
To start off, create an empty file called example.md
and give it a Markdown title and text.
We can now use the myst-docutils-demo
CLI tool, from the installed package, to parse this file to 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. Extend Markdown with MyST syntax#
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>
Tip
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.
Tip
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 content
::::{tab-set}
:::{tab-item} Label1
Content 1
:::
:::{tab-item} Label2
Content 2
:::
::::
Content 1
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
See also
sphinx-extensions, for a curated and opinionated list of Sphinx extensions.