Overview

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¶

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

ABC directive
```

type: root
children:
  - type: mystDirective
    name: abc
    args: foo bar
    value: |-
      :a: one
      :b: two

      ABC directive

: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

```{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¶

{abc}`ABC role`

type: root
children:
  - type: paragraph
    children:
      - type: mystRole
        name: abc
        value: 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: