Optional MyST Syntaxes

MyST-Parser is highly configurable, utilising the inherent “plugability” of the markdown-it-py parser. The following syntaxes are optional (disabled by default) and can be enabled via the sphinx conf.py (see MyST configuration options). Their goal is generally to add more Markdown friendly syntaxes; often enabling and rendering markdown-it-py plugins that extend the CommonMark specification.

Admonition directives

A special syntax for admonitions can optionally be enabled by setting myst_admonition_enable = True in the sphinx conf.py configuration file.

The key differences are that, instead of back-ticks, colons are used, and the content starts as regular Markdown. This has the benefit of allowing the content to be rendered correctly, when you are working in any standard Markdown editor. For example:

:::{note}
This text is **standard** _Markdown_
:::

Note

This text is standard Markdown

Similar to normal directives, these admonitions can also be nested:

::::{important}
:::{note}
This text is **standard** _Markdown_
:::
::::

Important

Note

This text is standard Markdown

The supported directives are: admonition, attention, caution, danger, error, important, hint, note, seealso, tip and warning.

These directives do not currently allow for parameters to be set, but you can add additional CSS classes to the admonition as comma-delimited arguments after the directive name. Also admonition can have a custom title. For example:

:::{admonition,warning} This *is* also **Markdown**
This text is **standard** _Markdown_
:::

This is also Markdown

This text is standard Markdown

Auto-generated header anchors

A common, extended Markdown syntax is to use header bookmark links, locally; [](#header-anchor), or cross-file [](path/to/file.md#header-anchor). To achieve this, section headings must be assigned anchors, which can be achieved in myst-parser, by setting myst_heading_anchors = 2 in your conf.py. This configures heading anchors to be assigned to both h1 and h2 level headings. The anchor “slugs” created aim to follow the GitHub implementation; lower-case text, removing punctuation, replacing spaces with -, uniqueness via suffix enumeration -1. You can inspect the links that will be created using the command-line tool:

$ myst-anchors -l 2 docs/using/syntax-optional.md
<h1 id="optional-myst-syntaxes"></h1>
<h2 id="admonition-directives"></h2>
<h2 id="auto-generated-header-anchors"></h2>
<h2 id="definition-lists"></h2>
<h2 id="images"></h2>
<h2 id="markdown-figures"></h2>
<h2 id="direct-latex-math"></h2>

For example [](#auto-generated-header-anchors): Auto-generated header anchors.

The paths to other files should be relative to the current file, for example [**link text**](./syntax.md#the-myst-syntax-guide): link text.

Definition Lists

By setting myst_deflist_enable = True in the sphinx conf.py configuration file, you will be able to utilise definition lists. Definition lists utlise the markdown-it-py deflist plugin, which itself is based on the Pandoc definition list specification.

This syntax can be useful, for example, as an alternative to nested bullet-lists:

  • Term 1

    • Definition

  • Term 2

    • Definition

Using instead:

Term 1
: Definition

Term 2
: Definition
Term 1

Definition

Term 2

Definition

From the Pandoc documentation:

Each term must fit on one line, which may optionally be followed by a blank line, and must be followed by one or more definitions. A definition begins with a colon or tilde, which may be indented one or two spaces.

A term may have multiple definitions, and each definition may consist of one or more block elements (paragraph, code block, list, etc.)

Here is a more complex example, demonstrating some of these features:

Term with Markdown

Definition with reference

A second paragraph

A second definition

Term 2

Definition 2a

Definition 2b

Term 3
A code block

A quote : A final definition, that can even include images:

fishy

This was created from:

Term *with Markdown*
: Definition [with reference](syntax/definition-lists)

  A second paragraph

Term 2
  ~ Definition 2a
  ~ Definition 2b

Term 3
:     A code block

: > A quote

: A final definition, that can even include images:

  <img src="img/fun-fish.png" alt="fishy" width="200px">

Images

MyST provides a few different syntaxes for including images in your documentation, as explained below.

The first is the standard Markdown syntax:

![fishy](img/fun-fish.png)

fishy

This will correctly copy the image to the build folder and will render it in all output formats (HTML, TeX, etc). However, it is limited in the configuration that can be applied, for example setting a width.

As discussed above, MyST allow for directives to be used such as image and figure (see the sphinx documentation):

```{image} img/fun-fish.png
:alt: fishy
:class: bg-primary
:width: 200px
:align: center
```
fishy

Additional options can now be set, however, in contrast to the Markdown syntax, this syntax will not show the image in common Markdown viewers (for example when the files are viewed on GitHub).

The final option is directly using HTML, which is also parsed by MyST. This is usually a bad option, because the HTML is treated as raw text during the build process and so sphinx will not recognise that the image file is to be copied, and will not output the HTML into non-HTML output formats.

HTML parsing to the rescue! By setting myst_html_img_enable = True in the sphinx conf.py configuration file, MySt-Parser will attempt to convert any isolated img tags (i.e. not wrapped in any other HTML) to the internal representation used in sphinx.

<img src="img/fun-fish.png" alt="fishy" class="bg-primary" width="200px">
fishy

Allowed attributes are equivalent to the image directive: src, alt, class, width, height and name. Any other attributes will be dropped.

Markdown Figures

Setting myst_figure_enable = True in your sphinx conf.py, combines the above two extended syntaxes, to create a fully Markdown compliant version of the figure directive.

The figure block must contain only two components; an image, in either Markdown or HTML syntax, and a single paragraph for the caption.

As with admonitions, the figure can have additional classes set on it, but the title is now taken as the reference target of the figure:

:::{figure,myclass} fig-target
<img src="img/fun-fish.png" alt="fishy" class="bg-primary mb-1" width="200px">

This is a caption in **Markdown**
:::
fishy

This is a caption in Markdown

As we see here, the target we set can be referenced:

[Go to the fish!](fig-target)

Go to the fish!

Direct LaTeX Math

You can enable direct parsing of amsmath LaTeX equations by setting myst_amsmath_enable = True in your sphinx conf.py. These top-level math environments will then be directly parsed:

equation, multline, gather, align, alignat, flalign, matrix, pmatrix, bmatrix, Bmatrix, vmatrix, Vmatrix, eqnarray.

As expected, environments ending in * will not be numbered, for example:

\begin{gather*}
a_1=b_1+c_1\\
a_2=b_2+c_2-d_2+e_2
\end{gather*}

\begin{align}
a_{11}& =b_{11}&
  a_{12}& =b_{12}\\
a_{21}& =b_{21}&
  a_{22}& =b_{22}+c_{22}
\end{align}
\[\begin{gather*} a_1=b_1+c_1\\ a_2=b_2+c_2-d_2+e_2 \end{gather*}\]
(1)\[\begin{align} a_{11}& =b_{11}& a_{12}& =b_{12}\\ a_{21}& =b_{21}& a_{22}& =b_{22}+c_{22} \end{align}\]

Note

\labels inside the environment are not currently identified, and so cannot be referenced. We hope to implement this in a future update (see executablebooks/MyST-Parser#202)!

This syntax will also work when nested in other block elements, like lists or quotes:

- A list
- \begin{gather*}
  a_1=b_1+c_1\\a_2=b_2+c_2-d_2+e_2
  \end{gather*}

> A block quote
> \begin{gather*}
  a_1=b_1+c_1\\a_2=b_2+c_2-d_2+e_2
  \end{gather*}
  • A list

  • \[\begin{gather*} a_1=b_1+c_1\\a_2=b_2+c_2-d_2+e_2 \end{gather*}\]

A block quote

\[\begin{gather*} a_1=b_1+c_1\\a_2=b_2+c_2-d_2+e_2 \end{gather*}\]