1.2.2. Directives

A directive is a generic block of Explicit Markup. Besides roles, it is one of the extension mechanisms of reStructuredText, and Sphinx makes heavy use of it.

Basically, a directive consists of a name, arguments, options and content. Keep this terminology in mind, it is used in section Explicit Markup describing custom directives. Looking at this example, that allows marking a block of content with special meaning.

basic directive syntax looks like this

the example

.. directive:: arg1 arg2 ...
   :option1: value
   :option2: value
   :option5: value
   ...

   Multiline content of the directive,
   ...

This line is no longer part of the block controlled by the directive.

directive

That is the directive name. It is given two arguments here.

arg1, arg2, ...

Arguments. The last argument can contain spaces (depending on the directive implementation).

:option0:, :option1:, ... :option9:

Options are optional. As you can see, options are given in the lines immediately following the arguments and indicated by the colons.

Multiline content of the directive,

The directive content follows after a blank line and is indented relative to the directive start.

Directives are supplied not only by Docutils, but Sphinx and custom extensions can add their own. Directives are written as a block.

Docutils supports the following directives (incomplete list):

• Admonitions: attention, caution, danger, error, hint, important, note, tip, warning and the generic admonition. (Most themes style only “note” and “warning” specially.)

• Images and Figures:

  • image

  • figure (an image with caption and optional legend)

• Additional body elements:

  • contents (a local, i.e. for the current file only, table of contents)

  • section numbering (automatically)

  • container (a container with a custom class, useful to generate an outer <div> in HTML)

  • rubric (a heading without relation to the document sectioning)

  • topic, sidebar (special highlighted body elements)

  • parsed-literal (literal block that supports inline markup)

  • epigraph (a block quote with optional attribution line)

  • highlights, pull-quote (block quotes with their own class attribute)

  • compound (a compound paragraph)

• Special Tables:

  • table (a table with title)

  • csv-table (a table generated from comma-separated values)

  • list-table (a table generated from a list of lists)

• Special directives and Include a Shared File:

  • raw (include raw target-format markup)

  • include (include reStructuredText from another file) – in Sphinx, when given an absolute include file path, this directive takes it as relative to the source directory

  • class (assign a class attribute to the next element) 1

• HTML specifics:

  • meta (generation of HTML <meta> tags, see also HTML Metadata below)

  • title (override document title)

• Influencing markup:

  • default-role (set a new default role)

  • role (create a new role)

  Since these are only per-file, better use Sphinx’s facilities for setting the default_role.

• References and Substitutions:

  • target footnotes (for each external URL target)

  • replacement text (for a substitution)

  • unicode characters (used in substitution)

Warning

Do not use the directives sectnum, header and footer.

See also

• Refer to Directives for directives provided by Docutils.

• Refer to Directives for directives added by Sphinx.

Footnotes

1

When the default domain contains a class directive, this directive will be shadowed. Therefore, Sphinx re-exports it as rst-class.