Get Started
Contents
Get Started#
This page describes how to get started with the MyST parser, with a focus on enabling it in the Sphinx documentation engine.
Installation#
To install use pip:
pip install myst-parser
or Conda:
conda install -c conda-forge myst-parser
Enable MyST in Sphinx#
To get started with Sphinx, see their Quickstart Guide.
To use the MyST parser in Sphinx, simply add the following to your conf.py file:
extensions = ["myst_parser"]
This will activate the MyST Parser extension, causing all documents with the .md extension to be parsed as MyST.
Tip
To parse single documents, see the Single Page Builds section
Write a CommonMark document#
MyST is an extension of CommonMark Markdown, that includes additional syntax for technical authoring, which integrates with Docutils and Sphinx.
To start off, create an empty file called myfile.md and give it a markdown title and text.
# My nifty title
Some **text**!
To parse to HTML, try the CLI:
$ myst-docutils-html5 --stylesheet= myfile.md
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1" />
<meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<title>My nifty title</title>
</head>
<body>
<main id="my-nifty-title">
<h1 class="title">My nifty title</h1>
<p>Some <strong>text</strong>!</p>
</main>
</body>
</html>
To include this document within a Sphinx project,
include myfile.md in a toctree directive on an index page.
Extend CommonMark with roles and directives#
MyST allows any Sphinx role or directive to be used in a document. These are extensions points allowing for richer features, such as admonitions and figures.
For example, add an admonition directive and sup role to your Markdown page, like so:
# My nifty title
Some **text**!
```{admonition} Here's my title
:class: tip
Here's my admonition content.{sup}`1`
```
Then convert to HTML:
$ myst-docutils-html5 --stylesheet= myfile.md
...
<div class="admonition tip">
<p class="admonition-title">Here's my title</p>
<p>Here's my admonition content.<sup>1</sup></p>
</div>
...
See also
The full Roles and Directives section
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:
(header-label)=
# A header
[My reference](header-label)
$ myst-docutils-html5 --stylesheet= myfile.md
...
<span id="header-label"></span>
<h1 class="title">A header</h1>
<p><a class="reference internal" href="#header-label">My reference</a></p>
...
See also
The Markdown Links and Referencing section,
and the ReadTheDocs cross-referencing documentation
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:
---
myst:
enable_extensions: ["colon_fence"]
---
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 sphinxcontib.mermaid extension,
which will allow us to generate Mermaid diagrams with MyST.
First, install sphinxcontrib.mermaid:
pip install sphinxcontrib-mermaid
Next, add it to your list of extensions in conf.py:
extensions = [
"myst_parser",
"sphinxcontrib.mermaid",
]
Now, add a mermaid directive to your markdown file. For example:
# My nifty title
Some **text**!
```{admonition} Here's my title
:class: warning
Here's my admonition content
```
(section-two)=
## Here's another section
And some more content.
% This comment won't make it into the outputs!
And here's {ref}`a reference to this section <section-two>`.
I can also reference the section {ref}`section-two` without specifying my title.
:::{note}
And here's a note with a colon fence!
:::
And finally, here's a cool mermaid diagram!
```{mermaid}
sequenceDiagram
participant Alice
participant Bob
Alice->John: Hello John, how are you?
loop Healthcheck
John->John: Fight against hypochondria
end
Note right of John: Rational thoughts <br/>prevail...
John-->Alice: Great!
John->Bob: How about you?
Bob-->John: Jolly good!
```
When you build your documentation, you should see something like this: