Overview - MyST Markdown

MyST (Markedly Structured Text) is designed to create publication-quality documents written entirely in Markdown. The main use case driving the development and design of MyST is JupyterBook, which helps you create educational online textbooks and tutorials with Jupyter Notebooks and narrative content written in MyST. The extensions and design of MyST is inspired by the Sphinx and ReStructured Text (RST) ecosystems.

MyST is designed to harness the extensibility and community of RST and bring these super-powers into Markdown.

MyST is a superset of CommonMark (the standard form of Markdown) and allows you to directly create “directives” and “roles” as extension points in the language. directives are block-level extension points, like callout panels, tabs, figures or embedded charts; and roles are inline extension points, for components like references or inline math.

Directives & Roles¶

Roles and directives are two of the most powerful parts of MyST. They are kind of like functions, but written in a markup language. They both serve a similar purpose, but roles are written in one line whereas directives span many lines. They both accept different kinds of inputs, and what they do with those inputs depends on the specific role or directive being used.

Directives¶

Directives are multi-line containers that include an identifier, arguments, options, and content. Examples include admonitions, figures, and equations.

Specification¶

Content block with predefined behavior

type: string, ("mystDirective"): See also Node
name: string: No description for this property.
args: string, optional: No description for this property.
options: object, optional: No description for this property.
value: string, optional: body of the directive, excluding options
children: array, optional, (FlowContent | PhrasingContent): parsed directive content
position: object, optional, (Position): See also Node
data: object, optional: See also Node

Example¶

Markup

AST

Render

```{abc} foo bar
:a: one
:b: two

ABC directive
```

In addition to the directive name and the directive content, directives allow two other configuration points:

1) directive arguments - a list of words that come just after the {directivename}.

```{directivename} arg1 arg2
My directive content.
```

2) directive options - a collection of flags or key/value pairs that come just underneath {directivename}.

There are two ways to write directive options

2a) Options as `:key: val` pairs. Great for a few options.	2b) Options as `key: val` pairs enclosed by `---` lines. This is parsed as YAML, and easier for listing many options.
```{directivename} :key1: metadata1 :key2: metadata2 My directive content. ```	```{directivename} --- key1: metadata1 key2: metadata2 --- My directive content. ```

Roles¶

Roles are very similar to directives, but they are written entirely in one line.

Specification¶

Custom in-line behavior

type: string, ("mystRole"): See also Node
name: string: No description for this property.
value: string, optional: content of the directive
children: array, optional, (PhrasingContent): parsed role content
position: object, optional, (Position): See also Node
data: object, optional: See also Node

Example¶

Markup

AST

Render

{abc}`ABC role`

Of course, roles will only allow custom behavior work if name is a valid role name! The abbr role creates inline abbreviations, for example, {abbr}`MyST (Markedly Structured Text)` will become MyST! When you hover over^[1] the abbreviation you will see the title appear!

Roles are defined inline, with an identifier and input. There are a number of roles included in MyST, including abbreviations, subscript, and superscript, as well as inline Math & Equations.

Nesting content blocks in Markdown¶

If you’d like to nest content blocks inside one another in Markdown (for example, to put a {note} inside of a {margin}), you may do so by adding extra backticks (`) to the outer-most block. This works for literal code blocks as well.

For example, the following syntax:

````
```
```
````

yields

```
```

Thus, if you’d like to nest directives inside one another, you can take the same approach. For example, the following syntax:

````{important}
```{note}
Here's my `important`, highly nested note! 🪆
```
````

produces a nested, important > note:

MyST Spec

CommonMark