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; androles
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:
- directive arguments - a list of words that come just after the
{directive_type}
```{directivename} arg1 arg2
My directive content.
```
- 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)`
.