MyST Syntax Reference

This page serves as a reference for the syntax that makes of MyST Markdown.

See also

For more description and explanation of MyST syntax, see the syntax guide.

Block (Multi-line) Tokens

Block tokens span multiple lines of content. They are broken down into two sections:

In addition to these summaries of block-level syntax, see Extra markdown syntax.

Note

Because MyST markdown was inspired by functionality that exists in reStructuredText, we have shown equivalent rST syntax for many MyST markdown features below.

Extended block tokens

Token

Description

Example

FrontMatter

A YAML block at the start of the document enclosed by ---

---
key: value
---

Directives

enclosed in 3 or more backticks followed by the directive name wrapped in curly brackets {}. See Directives - a block-level extension point for more details.

```{directive}
:option: value

content
```

Math

$$ (default) or \[\] characters wrapping multi-line math, or even direct amsmath LaTeX equations (optional). See Math shortcuts for more information.

$$
a=1
$$

Table

Standard markdown table style, with pipe separation.

| a    | b    |
| :--- | ---: |
| c    | d    |

LineComment

A commented line. See Comments for more information.

% this is a comment

BlockBreak

Define blocks of text. See Block Breaks for more information.

+++ {"meta": "data"}

Footnote

A definition for a referencing footnote, that is placed at the bottom of the document. See Footnotes for more details.

[^ref]: Some footnote text

Admonitions (optional)

An alternative approach for admonition style directives only, which has the benefit of allowing the content to be rendered in standard markdown editors. See admonition directives for more details.

:::{note}
*content*
:::

CommonMark tokens

Token

Description

Example

HTMLBlock

Any valid HTML (rendered in HTML output only)

<p>some text</p>

BlockCode

indented text (4 spaces or a tab)

    included as literal *text*

Heading

Level 1-6 headings, denoted by number of #

### Heading level 3

SetextHeading

Underlined header (using multiple = or -)

Header
======

Quote

quoted text

> this is a quote

CodeFence

enclosed in 3 or more backticks with an optional language name

```python
print('this is python')
```

ThematicBreak

Creates a horizontal line in the output

---

List

bullet points or enumerated.

- item
  - nested item
1. numbered item

LinkDefinition

A substitution for an inline link, which can have a reference target (no spaces), and an optional title (in ")

[key]: https://www.google.com "a title"

Paragraph

General inline text

any *text*

Span (Inline) Tokens

Span (or inline) tokens are defined on a single line of content. They are broken down into two sections below:

In addition to these summaries of inline syntax, see Extra markdown syntax.

Extended inline tokens

Token

Description

Example

Role

See Roles - an in-line extension point for more information.

{rolename}`interpreted text`

Target

Precedes element to target, e.g. header. See Targets and Cross-Referencing for more information.

(target)=

Math

$ (default) or \(\) enclosed math. See Math shortcuts for more information.

$a=1$ or $$a=1$$

FootReference

Reference a footnote. See Footnotes for more details.

[^abc]

CommonMark inline tokens

Token

Description

Example

HTMLSpan

Any valid HTML (rendered in HTML output only)

<p>some text</p>

EscapeSequence

Escaped symbols (to avoid them being interpreted as other syntax elements)

\*

AutoLink

Link that is shown in final output

<http://www.google.com>

InlineCode

Literal text

`a=1`

LineBreak

Soft or hard (ends with spaces or backslash)

A hard break\

Image

Link to an image. You can also use HTML syntax, to include image size etc, see here for details

![alt](src "title")

Link

Reference LinkDefinitions

[text](target "title") or [text][key]

Strong

Bold text

**strong**

Emphasis

Italic text

*emphasis*

RawText

Any text

any text