Follow us on TwitterFork us on GitHub
MyST Markdown

MyST Syntax Overview

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 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 cross-references, external references, citations, or inline math.

#Frontmatter

To add meta information to your document, you can add frontmatter that includes a title, description, thumbnail and any authors or scientific data like a doi. To include frontmatter, add it at the top of your document as YAML, for example:

---
title: MyST Syntax Overview
description: MyST is designed to create publication-quality documents written entirely in Markdown.
---

To learn about all the fields that you can add, see Frontmatter.

#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 the following markup:

```{note} Here is a note! ```

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.
```

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.

Key value pairs
YAML

Try editing the following {figure} directive, you can center the figure with an :align: center option!

```{figure} https://source.unsplash.com/random/400x200?meditation :align: right The picture would look better if it is `:align: center`-ed! ```

#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 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:

Here is an {abc}`unknown role`.

#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, two admonitions nested in side of eachother:

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