Skip To Article

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:

Footnotes
  1. Abbreviations are also great structured data for screen-readers!

MyST MarkdownMyST Markdown
Community-driven tools for the future of technical communication and publication, part of Jupyter.