MyST (Markedly Structured Text) is designed to create publication-quality documents written entirely in Markdown. The extensions and design of MyST is inspired by the Sphinx and reStructuredText (RST) ecosystems.
MyST is a superset of CommonMark, the standard form of Markdown, and allows you to directly create “directives” and “roles” that extend markdown to support technical and scientific documents. directives are block-level extension points, like callout panels, tabs, figures or embedded charts; and roles are inline extension points, for components like cross-references, external references, citations, 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. At its simplest, you can use directives using a “fence” (either back-ticks or colons[2]) and the name of the directive enclosed in braces ({name}):
The {note} directive above doesn’t take any arguments and we didn’t add any options. 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.
:::```{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, as :key: value or as a YAML block.
Options can be included as :key: val pairs, which is the default way to include options.
```{directivename}
:key1: metadata1
:key2: metadata2
My directive content.
```Options can also be included as key: val pairs enclosed by --- lines, similar to document frontmatter.
This is parsed as YAML, and may be easier for listing many options.
```{directivename}
---
key1: metadata1
key2: metadata2
---
My directive content.
```Roles¶
Roles are very similar to directives, but they are written entirely in one line. The syntax of a role is:
Some content {rolename}`and here is my role's content!`Of course, roles will only work if rolename 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 and Equations. Unknown roles will still be parsed as well:
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 (`)[3] to the outer-most block.
For example, two admonitions nested in side of each other:
This works for literal code blocks as well. For example, to show triple-backticks on this page we are using following syntax:
Which fence type, colon or backtick, is up to you, and either will work. The colon-fence has better fallback when the contents of the directive includes markdown in non-MyST renderers (like GitHub). The backtick-fence should be used when the contents of the directive is code-like (e.g. a diagram or math!).
Abbreviations are also great structured data for screen-readers!
