Syntax

Basically the syntax is the markdown syntax, following the CommonMarkdown spec, plus Sphinx’s roles and directives (that are the ones of reST plus a few more, and you can also define yours).

That means that roles are now:

{role}`content`

and directives

```{directivename} arguments
---
key1: val1
key2: val2
---
This is
directive content
```

or for sort options

```{directivename} arguments
:key1: val1
:key2: val2

This is
directive content
```

Using markdown syntax offers some advantages as simpler hyperlinks but also some drawbacks (e.g. missing literal blocks).

Directives

Directives can be nested by having more backticks in the outer blocks. In addition, inner blocks can (but do not need to) be indented:

    ````{note}
    The next info should be nested
        ```{warning}
        Here's my warning
        ```
    ````

Alternatively, colons can be used for markdown-friednly directives by simply adding "colon_fence" to myst_enable_extensions.

    :::{directive}
    ...
    :::

This syntax is specially useful for admonitions and tables with headers (table directive), as they are markdown compliant.

Math

The "dollarmath" extension allows to parse $ and $$ for math equations. In addition, setting myst_dmath_double_inline option to True allows for writing equations with $$ and inline context.

It is also possible to add labels to equations

$$
e = mc^2
$$ (myeq)

and reference it as

{eq}`myeq`

Substitutions

Substitutions are a replacement for reST substitutions. They require "substitution" in myst_enable_extensions.

Substitutions can be added to conf.py:

myst_substitutions = {
  "key1": "I'm a **substitution**"
}

or at the top of each file:

---
substitutions:
  key1: "I'm a **substitution**"
---

Substitutions are invoked as {{ key1 }} and accept Jinja2 expressions and env can be used to reference the Sphinx environment.

Special lists

Definition lists can be used by adding "deflist" to myst_enable_extensions:

Term 1
: Definition

Term 2
: Definition

Task lists require "tasklist" in myst_enable_extensions, and are used as

- [ ] An item that needs doing
- [x] An item that is complete

Field lists use "fieldlist" in myst_enable_extensions and their syntax looks like:

:short: line
:long:
  with 
  several
  lines

  or even paragraphs

Images

Beside the standard markdown syntax

![img](img/something.png)

and the option to use reST directives such as image or figure, there is the option to use a markdown compatible syntax.

Tables

Tables follow Github syntax

Footnotes

Footnotes are declared as [^name] and referenced as [^name]: description. They are auto-numbered unless an integer is used as name.

By default, a transition line will be placed before any footnotes.

Extra

Comments are declared with %.

Targets are (name)= and can be referenced following reST or markdown syntax:

{ref}`name`
{ref}`text <name>`
[](name)
[text](name)