Directives are reStructuredText’s block-level extension mechanism, and roles its
inline one. Docutils defines the standard set below; Sphinx and other tools add many
more (toctree, autofunction, :ref:,
:doc: and so on), which plain Docutils reports as unknown.
Directive syntax
.. image:: photo.png
:alt: The harbour at dusk
:width: 400px
.. note:: Content may start on the first line
and continue indented..., a space, the directive name, ::, then any arguments on
the same line; then, indented, options as a field list, a blank line, and the
content. Names are case-insensitive. Most directives accept the common options
:class: (CSS class names) and :name: (makes the element a
link target).
Admonitions
| Directive | Arguments | Purpose |
|---|---|---|
attention, caution, danger, error, hint, important, note, tip, warning | none | A box with that fixed title around the content. |
admonition | title, required | A box with the given title. |
Images
| Directive | Arguments | Options | Purpose |
|---|---|---|---|
image | URI, required | alt, height, width, scale, align, target, loading (HTML5 only) | An image; may also be used in a substitution as an inline image. |
figure | URI, required | image options plus figwidth, figclass, figname, align | An image with a caption (the first paragraph of content) and a legend (the rest). |
Body elements
| Directive | Arguments | Options | Purpose |
|---|---|---|---|
topic | title, required | A self-contained block set apart from the flow. | |
sidebar | title, optional | subtitle | Supplementary material shown beside the text. |
line-block | none | Deprecated; use | line blocks. | |
parsed-literal | none | A literal block in which inline markup is still processed. | |
code | language, optional | number-lines | Source code, highlighted with Pygments when available. |
math | none | Display maths in LaTeX syntax. | |
rubric | text, required | An informal heading that is not a section. | |
epigraph, highlights, pull-quote | none | Block quotes with those classes. | |
compound | none | Several body elements forming one paragraph. | |
container | class names, optional | A generic block, like HTML div. |
Tables
| Directive | Arguments | Options | Purpose |
|---|---|---|---|
table | caption, optional | align, width, widths | Gives a grid or simple table a caption. |
csv-table | caption, optional | header, header-rows, stub-columns, file, url, encoding, delim, quote, escape, keepspace, align, width, widths | A table from comma-separated values, inline or from a file. |
list-table | caption, optional | header-rows, stub-columns, align, width, widths | A table from a two-level bullet list. |
Document parts and references
| Directive | Arguments | Options | Purpose |
|---|---|---|---|
contents | title, optional | depth, local, backlinks (entry, top, none) | A generated table of contents. |
sectnum (section-numbering) | none | depth, prefix, suffix, start | Numbers the sections. |
header, footer | none | Content for page headers and footers. | |
target-notes | none | class | Footnotes listing the URLs of all external links. |
footnotes, citations | Planned for gathering notes in one place; not implemented. |
Directives for substitution definitions
| Directive | Arguments | Options | Purpose |
|---|---|---|---|
replace | none | The content, with inline markup, replaces the reference. | |
unicode | character codes (U+00A9, 0xA9, ©…) and text | ltrim, rtrim, trim | Characters by code; text after .. in the argument is a comment. |
date | strftime format, optional (default %Y-%m-%d) | The date the document was processed. | |
image | URI | as for images, except name | An inline image. |
raw | output formats | file, url, encoding | Raw output inline. |
Miscellaneous
| Directive | Arguments | Options | Purpose |
|---|---|---|---|
include | path, required (<name> for Docutils’ standard files) | start-line, end-line, start-after, end-before, literal, code, number-lines, encoding, tab-width, parser | Reads another file in, as markup or as literal or code text. |
raw | output formats, required (html, latex…) | file, url, encoding | Passes content unchanged to those writers only. |
class (rst-class) | class names, required | Adds classes to the next element, or to the indented content. | |
role | new role name, and optionally a base role in parentheses | class, format (for raw), language (for code) | Defines a custom role. |
default-role | role name, optional | Sets the role for plain `text`; without an argument, restores the default. | |
meta | none | HTML meta elements, as a field list. | |
title | text, required | Sets the document’s metadata title. | |
restructuredtext-test-directive | For testing Docutils only. |
Interpreted text roles
| Role | Aliases | Meaning |
|---|---|---|
:title-reference: | :title:, :t: | The title of a book or other work; the default role. |
:emphasis: | As *text*. | |
:strong: | As **text**. | |
:literal: | As ``text``, except that backslashes are processed. | |
:code: | Inline code; a custom role based on it can set language for highlighting. | |
:math: | Inline maths in LaTeX syntax. | |
:subscript: | :sub: | Subscript. |
:superscript: | :sup: | Superscript. |
:abbreviation: | :ab: | An abbreviation. |
:acronym: | :ac: | An acronym. |
:pep-reference: | :PEP: | A link to a Python Enhancement Proposal by number. |
:rfc-reference: | :RFC: | A link to an RFC by number, optionally number#anchor. |
:raw: | Raw output; usable only through a custom role with a format option. |