Directives

`admonition` directive¶

Callouts, or “admonitions”, highlight a particular block of text that exists slightly apart from the narrative of your page, such as a note or a warning.

The admonition kind can be determined by the directive name used (e.g. :::{tip} or :::{note}).

Alias: attention, caution, danger, error, important, hint, note, seealso, tip, warning, .callout-note, .callout-warning, .callout-important, .callout-tip, .callout-caution

Directive Argument (parsed)

The optional title of the admonition, if not supplied the admonition kind will be used.

Note that the argument parsing is different from Sphinx, which does not allow named admonitions to have custom titles.

Directive Body (parsed)

The body of the admonition. If there is no title and the body starts with bold text or a heading, that content will be used as the admonition title.

Options

class (string)

CSS classes to add to your admonition. Special classes include:

dropdown: turns the admonition into a <details> html element
simple: an admonition with “simple” styles
the name of an admonition, the first valid admonition name encountered will be used (e.g. tip). Note that if you provide conflicting class names, the first valid admonition name will be used.

icon (boolean)

Setting icon to false will hide the icon.

`aside` directive¶

Alias: margin, sidebar, topic

Directive Argument (parsed)

An optional title

Directive Body (parsed, required)

No description

Options

label (string): No description; Alias: name
class (string): No description

`bibliography` directive¶

Options

filter (string): No description

`blockquote` directive¶

Block quotes are used to indicate that the enclosed content forms an extended quotation. They may be followed by an inscription or attribution formed of a paragraph beginning with --, ---, or an em-dash.

Alias: epigraph, pull-quote

Directive Body (parsed)

The body of the quote, which may contain a special attribution paragraph that is turned into a caption

Options

label (string)

No description

Alias: name

class (string)

CSS classes to add to your blockquote. Special classes include:

pull-quote: used for a blockquote node which should attract attention
epigraph: used for a blockquote node that are usually found at the beginning of a document

`code` directive¶

A code-block environment with a language as the argument, and options for highlighting, showing line numbers, and an optional filename.

Alias: code-block, sourcecode

Directive Argument (string)

Code language, for example python or typescript

Directive Body (string)

The raw code to display for the code block.

Options

label (string): No description; Alias: name
class (string): No description
caption (parsed): A parsed caption for the code block.
linenos (boolean): Show line numbers
lineno-start (number): Start line numbering from a particular value, default is 1. If present, line numbering is activated.
number-lines (number): Alternative for “lineno-start”, turns on line numbering and can be an integer that is the start of the line numbering.
emphasize-lines (string): Emphasize particular lines (comma-separated numbers), e.g. “3,5”
filename (string): Show the filename in addition to the rendered code. The include directive will use the filename by default, to turn off this default set the filename to false.

`code-cell` directive¶

An executable code cell

Directive Argument (string)

Language for execution and display, for example python. It will default to the language of the notebook or containing markdown file.

Directive Body (string)

The code to be executed and displayed.

Options

label (string): No description; Alias: name
tags (string): A comma-separated list of tags to add to the cell, for example, remove-input or hide-cell.; Alias: tag

`csv-table` directive¶

The “csv-table” directive is used to create a table from CSV (comma-separated values) data.

Directive Argument (parsed)

An optional table caption

Directive Body (string, required)

The CSV content

Options

label (string)

No description

Alias: name

header (string)

Supplemental data for the table header, added independently of and before any header-rows from the main CSV data. Must use the same CSV format as the main CSV data.

header-rows (number)

The number of rows of CSV data to use in the table header. Defaults to 0.

class (string)

CSS classes to add to your table. Special classes include:

full-width: changes the table environment to cover two columns in LaTeX

align (string)

No description

delim (string)

The character used to separate data fields. The special values “tab” and “space” are converted to the respective whitespace characters. Defaults to “,” (comma)

keepspace (boolean)

Treat whitespace immediately following the delimiter as significant. The default is to ignore such whitespace.

quote (string)

The character used to quote fields containing special characters, such as the delimiter, quotes, or new-line characters. Must be a single character, defaults to " (a double quote)
For example, First cell, "These commas, for example, are escaped", Next cell

escape (string)

A character used to escape the delimiter or quote characters from the CSV parser. Must be a single character, defaults to " (a double quote) default is a double quote
For example, First cell, "These quotes"", for example, are escaped", Next cell

Directive Argument (parsed)

No description

Directive Body (parsed, required)

No description

Options

open (boolean): No description

`embed` directive¶

The embed directive allows you to duplicate content from another part of your project. This can also be done through the figure directive.

Directive Argument (string, required)

The label of the node that you are embedding.

Options

remove-input (boolean): No description
remove-output (boolean): No description

`figure` directive¶

Directive Argument (string)

The filename of an image (e.g. my-fig.png), or an ID of a Jupyter Notebook cell (e.g. #my-cell).

Directive Body (parsed)

If an argument is provided to the figure directive, the body will be the figure caption. You may also omit the figure directive argument and provide images in the body of the figure, these will be parsed into sub figures.

Options

label (string)

No description

Alias: name

class (string)

CSS classes to add to your figure. Special classes include:

full-width: changes the figure environment to cover two columns in LaTeX

Alias: figclass

height (string)

The figure height, in CSS units, for example 4em or 300px.

Alias: h

width (string)

The figure width, in CSS units, for example 50% or 300px.

Alias: w, figwidth

alt (string)

Alternative text for the image

align (string)

The alignment of the image in the figure. Choose one of left, center or right

remove-input (boolean)

If the argument is a notebook cell, use this flag to remove the input code from the cell.

remove-output (boolean)

If the argument is a notebook cell, use this flag to remove the output from the cell.

placeholder (string)

A placeholder image when using a notebook cell as the figure contents. This will be shown in place of the Jupyter output until an execution environment is attached. It will also be used in static outputs, such as a PDF output.

no-subfigures (boolean)

Disallow implicit subfigure creation from child nodes

Alias: no-subfig, no-subfigure

kind (string)

Override the figures “kind”, which changes the enumeration to start counting independently for that kind. For example, kind: "example". The default enumeration and referencing will be the capitalized kind followed by a number (e.g. “Example 1”).

`glossary` directive¶

Directive Body (parsed, required): No description
Options: No options

`iframe` directive¶

Directive Argument (string, required)

The URL source (src) of the HTML iframe element.

Directive Body (parsed)

If provided, this will be the iframe caption.

Options

label (string): No description; Alias: name
class (string): No description
width (string): The iframe width, in CSS units, for example 50% or 300px.
align (string): The alignment of the iframe in the page. Choose one of left, center or right

`image` directive¶

Directive Argument (string, required)

The filename of an image (e.g. my-fig.png).

Options

class (string): No description
height (string): The image height, in CSS units, for example 4em or 300px.; Alias: h
width (string): The image width, in CSS units, for example 50% or 300px.; Alias: w
alt (string): Alternative text for the image
align (string): The alignment of the image. Choose one of left, center or right
title (string): Title text for the image

`include` directive¶

Allows you to include the source or parsed version of a separate file into your document tree.

Alias: literalinclude

Directive Argument (string, required)

The file path, which is relative to the file from which it was referenced.

Options

label (string): No description; Alias: name
literal (boolean): Flag the include block as literal, and show the contents as a code block. This can also be set automatically by setting the language or using the literalinclude directive.
lang (string): The language of the code to be highlighted as. If set, this automatically changes an include into a literalinclude.; Alias: language, code
caption (parsed): A parsed caption for the code block.
linenos (boolean): Show line numbers
lineno-start (number): Start line numbering from a particular value, default is 1. If present, line numbering is activated.
number-lines (number): Alternative for “lineno-start”, turns on line numbering and can be an integer that is the start of the line numbering.
emphasize-lines (string): Emphasize particular lines (comma-separated numbers), e.g. “3,5”
filename (string): Show the filename in addition to the rendered code. The include directive will use the filename by default, to turn off this default set the filename to false.
start-line (number): Only the content starting from this line will be included. The first line has index 0 and negative values count from the end.
start-at (string): Only the content after and including the first occurrence of the specified text in the external data file will be included.
start-after (string): Only the content after the first occurrence of the specified text in the external data file will be included.
end-line (number): Only the content up to (but excluding) this line will be included.
end-at (string): Only the content up to and including the first occurrence of the specified text in the external data file (but after any start-after text) will be included.
end-before (string): Only the content before the first occurrence of the specified text in the external data file (but after any start-after text) will be included.
lines (string): Specify exactly which lines to include from the original file, starting at 1. For example, 1,3,5-10,20- includes the lines 1, 3, 5 to 10 and lines 20 to the last line of the original file.
lineno-match (boolean): Display the original line numbers, correct only when the selection consists of contiguous lines.

`list-table` directive¶

Directive Argument (parsed)

An optional table caption

Directive Body (parsed, required)

No description

Options

label (string)

No description

Alias: name

header-rows (number)

No description

class (string)

CSS classes to add to your table. Special classes include:

full-width: changes the table environment to cover two columns in LaTeX

align (string)

No description

`math` directive¶

Directive Body (string, required)

No description

Options

label (string): No description; Alias: name

`mdast` directive¶

Directive Argument (string, required): No description
Options: No options

`mermaid` directive¶

Directive Body (string, required): No description
Options: No options

`myst` directive¶

Directive Body (string, required)

No description

Options

numbering (string): No description

`output` directive¶

Options

id (string, required): No description

`table` directive¶

Directive Argument (parsed)

An optional table caption

Directive Body (parsed, required)

No description

Options

label (string)

No description

Alias: name

class (string)

CSS classes to add to your table. Special classes include:

full-width: changes the table environment to cover two columns in LaTeX

align (string)

No description

admonition directive¶

aside directive¶

bibliography directive¶

blockquote directive¶

code directive¶

code-cell directive¶

csv-table directive¶

dropdown directive¶

embed directive¶

figure directive¶

glossary directive¶

iframe directive¶

image directive¶

include directive¶

list-table directive¶

math directive¶

mdast directive¶

mermaid directive¶

myst directive¶

output directive¶

table directive¶

`admonition` directive¶

`aside` directive¶

`bibliography` directive¶

`blockquote` directive¶

`code` directive¶

`code-cell` directive¶

`csv-table` directive¶

`dropdown` directive¶

`embed` directive¶

`figure` directive¶

`glossary` directive¶

`iframe` directive¶

`image` directive¶

`include` directive¶

`list-table` directive¶

`math` directive¶

`mdast` directive¶

`mermaid` directive¶

`myst` directive¶

`output` directive¶

`table` directive¶