reStructuredText Directives (original) (raw)

David Goodger

Contact:

docutils-develop@lists.sourceforge.net

Revision:

10113

Date:

2025-04-29

This document has been placed in the public domain.

Contents

Admonitions
- Specific Admonitions
- Generic Admonition
Images
- Image
- Figure
Body Elements
- Topic
- Sidebar
- Line Block
- Parsed Literal Block
- Code
- Math
- Rubric
- Epigraph
- Highlights
- Pull-Quote
- Compound Paragraph
- Container
Tables
Document Parts
References
Directives for Substitution Definitions
Miscellaneous
Common Options
Common Option Value Types

This document describes the directives implemented in the reference reStructuredText parser.

Directives have the following syntax:

+-------+-------------------------------+ | ".. " | directive type "::" directive | +-------+ block | | | +-------------------------------+

Directives begin with an explicit markup start (two periods and a space), followed by the directive type and two colons (collectively, the "directive marker"). The directive block begins immediately after the directive marker, and includes all subsequent indented lines. The directive block is divided into arguments, options (a field list), and content (in that order), any of which may appear. See the Directivessection in the reStructuredText Markup Specification for syntax details.

Descriptions below list "doctree elements" (document tree element names; XML DTD generic identifiers) corresponding to individual directives. For details on the hierarchy of elements, please see The Docutils Document Tree and the Docutils Generic DTD XML document type definition. For directive implementation details, see Creating reStructuredText Directives and the source.

Admonitions

Admonitions ("safety messages" or "hazard statements") can appear anywhere an ordinary body element can. They contain arbitrary body elements. Typically, an admonition is rendered as an offset block in a document, sometimes outlined or shaded.

Docutils defines a generic admonition as well as a set ofspecific admonitions.

Specific Admonitions

Directive Types:

"attention", "caution", "danger", "error", "hint", "important", "note", "tip", "warning"

Doctree Elements:

, , ,, , ,, ,

Directive Arguments:

none

Directive Options:

class, name

Directive Content:

Interpreted as body elements.

Specific admonitions are rendered with a title matching the admonition type. For example:

.. DANGER:: Beware killer rabbits!

This directive might be rendered something like this:

+------------------------+ | !DANGER! | | | | Beware killer rabbits! | +------------------------+

Any text immediately following the directive indicator (on the same line and/or indented on following lines) is interpreted as a directive block and is parsed for normal body elements. For example, the following "note" admonition directive contains one paragraph and a bullet list consisting of two list items:

.. note:: This is a note admonition. This is the second line of the first paragraph.

The note contains all indented body elements following.
It includes this bullet list.

Generic Admonition

Directive Type:

"admonition"

Doctree Elements: