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.

`bibliography` directive¶

Options

filter (string): No description

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

Directive Argument (string, required)

No description

Directive Body (string)

No description

Options

tags (string): No description

Directive Argument (parsed)

No description

Directive Body (parsed, required)

No description

Options

open (boolean): No description

`embed` directive¶

Directive Argument (string, required)

No description

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.

`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.

`table` directive¶

Directive Argument (parsed)

No description

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

`list-table` directive¶

Directive Argument (parsed)

No description

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

`margin` directive¶

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

`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

admonition directive¶

bibliography directive¶

code directive¶

code-cell directive¶

dropdown directive¶

embed directive¶

figure directive¶

glossary directive¶

iframe directive¶

image directive¶

include directive¶

table directive¶

list-table directive¶

margin directive¶

math directive¶

mdast directive¶

mermaid directive¶

myst directive¶

output directive¶

`admonition` directive¶

`bibliography` directive¶

`code` directive¶

`code-cell` directive¶

`dropdown` directive¶

`embed` directive¶

`figure` directive¶

`glossary` directive¶

`iframe` directive¶

`image` directive¶

`include` directive¶

`table` directive¶

`list-table` directive¶

`margin` directive¶

`math` directive¶

`mdast` directive¶

`mermaid` directive¶

`myst` directive¶

`output` directive¶