Working with markdown

Curvenote uses a flavour of Markdown called MyST (Markedly Structured Text), which is designed to create publication-quality, computational documents written entirely in Markdown.

MyST Markdown Overview¶

MyST is a superset of CommonMark (a standard form of Markdown) and allows you to directly create “directives” and “roles” as extension points in the markup 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, citations, or inline math.

MyST is influenced by ReStructured Text (RST) and Sphinx – pulling on the nomenclature and introducing additional standards where appropriate.

Directives¶

Directives are multi-line containers that include a type, arguments, options, and content. Examples include callout panels, figures, and equations. At its simplest, you can use directives using the following markup:

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

The directive above is of type note, and doesn’t take any arguments and we didn’t provide 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 {directive_type}

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

2. directive options - a collection of key/value pairs that come just below {directive_type}

```{directivename}
:key1: metadata1
:key2: metadata2

My directive content.
```

Roles¶

Roles are inline extension points for things like abbreviations, references, citations, or interactive widgets. The syntax of a role is:

My inline role: {abc}`my-role`.

Both roles and directives enclose the type information in braces (i.e. {type}). Roles enclose all inputs inside of the `backticks`. Some roles treat the input differently, for example, an abbreviation role, {abbr}, will parse the abbreviation title from inside of parentheses {abbr}`MyST (Markedly Structured Text)`.