Roles and Directives
Contents
Roles and Directives#
Roles and directives provide a way to extend the syntax of MyST in an unbound manner, by interpreting a chuck of text as a specific type of markup, according to its name.
Mostly all docutils roles, docutils directives, sphinx roles, or sphinx directives can be used in MyST.
Syntax#
Directives - a block-level extension point#
Directives syntax is defined with triple-backticks and curly-brackets. It is effectively a Markdown code fence with curly brackets around the language, and a directive name in place of a language name. Here is the basic structure:
MyST |
reStructuredText |
---|---|
```{directivename} arguments
---
key1: val1
key2: val2
---
This is
directive content
```
|
.. directivename:: arguments
:key1: val1
:key2: val2
This is
directive content
|
For example, the following code:
```{admonition} This is my admonition
This is my note
```
Will generate this admonition:
This is my admonition
This is my note
Parameterizing directives#
For directives that take parameters as input, there are two ways to parameterize them.
In each case, the options themselves are given as key: value
pairs. An example of
each is shown below:
Using YAML frontmatter. A block of YAML front-matter just after the
first line of the directive will be parsed as options for the directive. This needs to be
surrounded by ---
lines. Everything in between will be parsed by YAML and
passed as keyword arguments to your directive. For example:
```{code-block} python
---
lineno-start: 10
emphasize-lines: 1, 3
caption: |
This is my
multi-line caption. It is *pretty nifty* ;-)
---
a = 2
print('my 1st line')
print(f'my {a}nd line')
```
10a = 2
11print('my 1st line')
12print(f'my {a}nd line')
Short-hand options with :
characters. If you only need one or two options for your
directive and wish to save lines, you may also specify directive options as a collection
of lines just after the first line of the directive, each preceding with :
. Then the
leading :
is removed from each line, and the rest is parsed as YAML.
For example:
```{code-block} python
:lineno-start: 10
:emphasize-lines: 1, 3
a = 2
print('my 1st line')
print(f'my {a}nd line')
```
How directives parse content#
Some directives parse the content that is in their content block. MyST parses this content as Markdown.
This means that MyST markdown can be written in the content areas of any directives written in MyST markdown. For example:
```{admonition} My markdown link
Here is [markdown link syntax](https://jupyter.org)
```
My markdown link
Here is markdown link syntax
As a short-hand for directives that require no arguments, and when no parameter options are used (see below), you may start the content directly after the directive name.
```{note} Notes require **no** arguments, so content can start here.
```
Note
Notes require no arguments, so content can start here.
For special cases, MySt also offers the eval-rst
directive.
This will parse the content as ReStructuredText:
```{eval-rst}
.. figure:: img/fun-fish.png
:width: 100px
:name: rst-fun-fish
Party time!
A reference from inside: :ref:`rst-fun-fish`
A reference from outside: :ref:`syntax/directives/parsing`
```
A reference from inside: Party time!
A reference from outside: How directives parse content
Note how the text is integrated into the rest of the document, so we can also reference party fish anywhere else in the documentation.
Nesting directives#
You can nest directives by ensuring that the tick-lines corresponding to the outermost directive are longer than the tick-lines for the inner directives. For example, nest a warning inside a note block like so:
````{note}
The next info should be nested
```{warning}
Here's my warning
```
````
Here’s how it looks rendered:
Note
The next info should be nested
Warning
Here’s my warning
You can indent inner-code fences, so long as they aren’t indented by more than 3 spaces. Otherwise, they will be rendered as “raw code” blocks:
````{note}
The warning block will be properly-parsed
```{warning}
Here's my warning
```
But the next block will be parsed as raw text
```{warning}
Here's my raw text warning that isn't parsed...
```
````
Note
The warning block will be properly-parsed
Warning
Here’s my warning
But the next block will be parsed as raw text
```{warning}
Here's my raw text warning that isn't parsed...
```
This can really be abused if you’d like ;-)
Note
The next info should be nested
Warning
Here’s my warning
Yep another admonition
# All this fuss was about this boring python?!
print('yep!')
Markdown-friendly directives#
Want to use syntax that renders correctly in standard Markdown editors? See the extended syntax option.
:::{note}
This text is **standard** *Markdown*
:::
Note
This text is standard Markdown
Roles - an in-line extension point#
Roles are similar to directives - they allow you to define arbitrary new functionality, but they are used in-line. To define an in-line role, use the following form:
MyST |
reStructuredText |
---|---|
{role-name}`role content`
|
:role-name:`role content`
|
For example, the following code:
Since Pythagoras, we know that {math}`a^2 + b^2 = c^2`
Becomes:
Since Pythagoras, we know that \(a^2 + b^2 = c^2\)
You can use roles to do things like reference equations and other items in your book. For example:
```{math} e^{i\pi} + 1 = 0
---
label: euler
---
```
Euler's identity, equation {math:numref}`euler`, was elected one of the
most beautiful mathematical formulas.
Becomes:
Euler’s identity, equation (1), was elected one of the most beautiful mathematical formulas.
How roles parse content#
The content of roles is parsed differently depending on the role that you’ve used.
Some roles expect inputs that will be used to change functionality. For example,
the ref
role will assume that input content is a reference to some other part of the
site. However, other roles may use the MyST parser to parse the input as content.
Some roles also extend their functionality depending on the content that you pass.
For example, following the ref
example above, if you pass a string like this:
Content to display <myref>
, then the ref
will display Content to display
and use
myref
as the reference to look up.
How roles parse this content depends on the author that created the role.
Common roles and directives#
ToC Trees#
- Name
contents
- Description
Insert a table of contents tree of the documents headings.
- Arguments
0 required, 1 optional
- Content
no
- Options
name
type
depth
integer (non-negative)
local
flag
backlinks
class
space-delimited list
- Name
toctree
- Description
Inserts a Sphinx “Table of Contents” tree, containing a list of (relative) child document paths.
- Arguments
0 required, 0 optional
- Content
yes
- Options
name
type
maxdepth
integer
name
text
caption
text
glob
flag
hidden
flag
includehidden
flag
numbered
integer
titlesonly
flag
reversed
flag
Admonitions#
- Name
admonition
- Description
Create a generic “callout” box, containing the content.
- Arguments
1 required, 0 optional
- Content
yes
- Options
name
type
class
space-delimited list
name
text
- Name
note
- Description
Create a “callout” box, specific to notes, containing the content.
- Arguments
0 required, 0 optional
- Content
yes
- Options
name
type
class
space-delimited list
name
text
Other admonitions (same structure as note
): attention
, caution
, danger
, error
, hint
, important
, tip
, warning
.
Sphinx only: deprecated
, versionadded
, versionchanged
.
Images and Figures#
- Name
image
- Description
Insert an image, from a (relative) path or URL.
- Arguments
1 required, 0 optional
- Content
no
- Options
name
type
alt
text
height
length or unitless
width
length, percentage or unitless
scale
percentage
align
target
text
class
space-delimited list
name
text
- Name
figure
- Description
Insert an image, from a (relative) path or URL, with a caption (first paragraph), and optional legend (subsequent content).
- Arguments
1 required, 0 optional
- Content
yes
- Options
name
type
alt
text
height
length or unitless
width
length, percentage or unitless
scale
percentage
align
target
text
class
space-delimited list
name
text
figwidth
figclass
space-delimited list
- Name
table
- Description
Insert a (MyST) table with a caption.
- Arguments
0 required, 1 optional
- Content
yes
- Options
name
type
class
space-delimited list
name
text
align
width
length, percentage or unitless
widths
Tables#
- Name
list-table
- Description
Create a table from data in a uniform two-level bullet list.
- Arguments
0 required, 1 optional
- Content
yes
- Options
name
type
header-rows
integer (non-negative)
stub-columns
integer (non-negative)
width
length, percentage or unitless
widths
class
space-delimited list
name
text
align
- Name
csv-table
- Description
Create a table from CSV (comma-separated values) data.
- Arguments
0 required, 1 optional
- Content
yes
- Options
name
type
header-rows
integer (non-negative)
stub-columns
integer (non-negative)
header
text
width
length, percentage or unitless
widths
file
path
url
URI
encoding
class
space-delimited list
name
text
align
delim
keepspace
flag
quote
escape
Code#
- Name
code-block
- Description
Syntax highlight a block of code, according to the language.
- Arguments
0 required, 1 optional
- Content
yes
- Options
name
type
force
flag
linenos
flag
dedent
lineno-start
integer
emphasize-lines
text
caption
text
class
space-delimited list
name
text
MyST only#
This section contains information about special roles and directives that come bundled with the MyST Parser Sphinx extension.
Insert the date and reading time#
New in version 0.14.0: The sub-ref
role and word counting.
You may insert the “last updated” date and estimated reading time into your document via substitution definitions, which can be accessed via the sub-ref
role.
For example:
> {sub-ref}`today` | {sub-ref}`wordcount-words` words | {sub-ref}`wordcount-minutes` min read
Jun 07, 2022 | 1149 words | 6 min read
today
is replaced by either the date on which the document is parsed, with the format set by today_fmt
, or the today
variable if set in the configuration file.
The reading speed is computed using the myst_words_per_minute
configuration (see the Sphinx configuration options).