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

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.

label (string)

Label the admonition to be cross-referenced or explicitly linked to.

Alias: name

enumerated (boolean)

Turn on/off the numbering for the specific admonition

Alias: numbered

enumerator (string)

Explicitly set the admonition number

Alias: number

icon (boolean)

Setting icon to false will hide the icon.

open (boolean)

Turn the admonition into a dropdown, if it isn’t already, and set the open state.

`aside` directive¶

Alias: margin, sidebar, topic

Directive Argument (parsed)

An optional title

Directive Body (parsed, required)

No description

Options

class (string): Annotate the aside with a set of space-delimited class names.
label (string): Label the aside to be cross-referenced or explicitly linked to.; Alias: name
enumerated (boolean): Turn on/off the numbering for the specific aside; Alias: numbered
enumerator (string): Explicitly set the aside number; Alias: number

`bibliography` directive¶

Options

class (string): Annotate the bibliography with a set of space-delimited class names.
label (string): Label the bibliography to be cross-referenced or explicitly linked to.; Alias: name
enumerated (boolean): Turn on/off the numbering for the specific bibliography; Alias: numbered
enumerator (string): Explicitly set the bibliography number; Alias: number
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

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

label (string)

Label the blockquote to be cross-referenced or explicitly linked to.

Alias: name

enumerated (boolean)

Turn on/off the numbering for the specific blockquote

Alias: numbered

enumerator (string)

Explicitly set the blockquote number

Alias: number

`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

class (string): Annotate the code with a set of space-delimited class names.
label (string): Label the code to be cross-referenced or explicitly linked to.; Alias: name
enumerated (boolean): Turn on/off the numbering for the specific code; Alias: numbered
enumerator (string): Explicitly set the code number; Alias: number
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

class (string): Annotate the code-cell with a set of space-delimited class names.
label (string): Label the code-cell to be cross-referenced or explicitly linked to.; Alias: name
enumerated (boolean): Turn on/off the numbering for the specific code-cell; Alias: numbered
enumerator (string): Explicitly set the code-cell number; Alias: number
caption (parsed): A parsed caption for the code output.
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

class (string)

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

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

label (string)

Label the CSV table to be cross-referenced or explicitly linked to.

Alias: name

enumerated (boolean)

Turn on/off the numbering for the specific CSV table

Alias: numbered

enumerator (string)

Explicitly set the CSV table number

Alias: number

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.

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

class (string): Annotate the dropdown with a set of space-delimited class names.
label (string): Label the dropdown to be cross-referenced or explicitly linked to.; Alias: name
enumerated (boolean): Turn on/off the numbering for the specific dropdown; Alias: numbered
enumerator (string): Explicitly set the dropdown number; Alias: number
open (boolean): When true, the dropdown starts open.

`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

class (string): Annotate the embed with a set of space-delimited class names.
label (string): Label the embed to be cross-referenced or explicitly linked to.; Alias: name
enumerated (boolean): Turn on/off the numbering for the specific embed; Alias: numbered
enumerator (string): Explicitly set the embed number; Alias: number
remove-input (boolean): If embedding a Jupyter Notebook cell, remove the input of the cell.
remove-output (boolean): If embedding a Jupyter Notebook cell, remove the output of the cell.

`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

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

label (string)

Label the figure to be cross-referenced or explicitly linked to.

Alias: name

enumerated (boolean)

Turn on/off the numbering for the specific figure

Alias: numbered

enumerator (string)

Explicitly set the figure number

Alias: number

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

class (string): Annotate the glossary with a set of space-delimited class names.
label (string): Label the glossary to be cross-referenced or explicitly linked to.; Alias: name
enumerated (boolean): Turn on/off the numbering for the specific glossary; Alias: numbered
enumerator (string): Explicitly set the glossary number; Alias: number

`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

class (string): Annotate the iframe with a set of space-delimited class names.
label (string): Label the iframe to be cross-referenced or explicitly linked to.; Alias: name
enumerated (boolean): Turn on/off the numbering for the specific iframe; Alias: numbered
enumerator (string): Explicitly set the iframe number; Alias: number
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
placeholder (string): A placeholder image for the iframe in static exports.

`image` directive¶

Directive Argument (string, required)

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

Options

class (string): Annotate the image with a set of space-delimited class names.
label (string): Label the image to be cross-referenced or explicitly linked to.; Alias: name
enumerated (boolean): Turn on/off the numbering for the specific image; Alias: numbered
enumerator (string): Explicitly set the image number; Alias: number
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

class (string): Annotate the include with a set of space-delimited class names.
label (string): Label the include to be cross-referenced or explicitly linked to.; Alias: name
enumerated (boolean): Turn on/off the numbering for the specific include; Alias: numbered
enumerator (string): Explicitly set the include number; Alias: number
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

class (string)

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

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

label (string)

Label the list table to be cross-referenced or explicitly linked to.

Alias: name

enumerated (boolean)

Turn on/off the numbering for the specific list table

Alias: numbered

enumerator (string)

Explicitly set the list table number

Alias: number

header-rows (number)

No description

align (string)

No description

`math` directive¶

Directive Body (string, required)

No description

Options

class (string): Annotate the math with a set of space-delimited class names.
label (string): Label the math to be cross-referenced or explicitly linked to.; Alias: name
enumerated (boolean): Turn on/off the numbering for the specific math; Alias: numbered
enumerator (string): Explicitly set the math number; Alias: number

`mdast` directive¶

Directive Argument (string, required)

No description

Options

class (string): Annotate the mdast with a set of space-delimited class names.
label (string): Label the mdast to be cross-referenced or explicitly linked to.; Alias: name
enumerated (boolean): Turn on/off the numbering for the specific mdast; Alias: numbered
enumerator (string): Explicitly set the mdast number; Alias: number

`mermaid` directive¶

Directive Body (string, required)

No description

Options

class (string): Annotate the mermaid with a set of space-delimited class names.
label (string): Label the mermaid to be cross-referenced or explicitly linked to.; Alias: name
enumerated (boolean): Turn on/off the numbering for the specific mermaid; Alias: numbered
enumerator (string): Explicitly set the mermaid number; Alias: number

`myst` directive¶

Directive Body (string, required)

No description

Options

class (string): Annotate the myst with a set of space-delimited class names.
label (string): Label the myst to be cross-referenced or explicitly linked to.; Alias: name
enumerated (boolean): Turn on/off the numbering for the specific myst; Alias: numbered
enumerator (string): Explicitly set the myst number; Alias: number
numbering (string): No description

`table` directive¶

Directive Argument (parsed)

An optional table caption

Directive Body (parsed, required)

No description

Options

class (string)

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

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

label (string)

Label the table to be cross-referenced or explicitly linked to.

Alias: name

enumerated (boolean)

Turn on/off the numbering for the specific table

Alias: numbered

enumerator (string)

Explicitly set the table number

Alias: number

align (string)

No description

`toc` directive¶

Inserts table of contents in the page. This may be for the project (each page has an entry), the current page (each heading has an entry), or the current section (only headings in the section have an entry).

Alias: tableofcontents, table-of-contents, toctree, contents

Directive Argument (parsed)

Heading to be included with table of contents

Options

context (string): Table of Contents context; one of project, page, or section; Alias: kind
depth (number): Number of levels to include in Table of Contents; by default, all levels will be included; Alias: maxdepth
class (string): Annotate the toc with a set of space-delimited class names.
label (string): Label the toc to be cross-referenced or explicitly linked to.; Alias: name
enumerated (boolean): Turn on/off the numbering for the specific toc; Alias: numbered
enumerator (string): Explicitly set the toc number; Alias: number

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¶

table directive¶

toc 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¶

`table` directive¶

`toc` directive¶