πŸš€ 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#

PyPI Conda

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 Title

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.