reStructuredText: Admonitions Examples

Note

This page was Retrieved and copied March 10 2021

https://twitter.com/ThomasConnors/status/1266413879388758017

Admonitions

Begin Webster’s example

Specific Admonitions

Admonitions are specially marked “topics” that 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, 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! |
+------------------------+

Danger

Beware killer rabbits!

The following admonition directives have been implemented:

  • attention

  • caution

  • danger

  • error

  • hint

  • important

  • note

  • tip

  • warning

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.

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

admonition_, title

Directive Arguments

One, required (admonition title)

Directive Options

Possible, see below.

Directive Content

Interpreted as body elements.

This is a generic, titled admonition. The title may be anything the author desires.

The author-supplied title is also used as a `"classes"`_ attribute value after being converted into a valid identifier form (down-cased; non-alphanumeric characters converted to single hyphens; “admonition-” prefixed). For example, this admonition:

.. admonition:: And, by the way...

   You can make up your own admonition too.

And, by the way…

You can make up your own admonition too.

becomes the following document tree (pseudo-XML):

<document source="test data">
    <admonition classes="admonition-and-by-the-way">
        <title>
            And, by the way...
        <paragraph>
            You can make up your own admonition too.

The common options are recognized:

classtext

Overrides the computed `"classes"`_ attribute value.

nametext

Add text to the `"names"`_ attribute of the admonition element.

Common Options

Most of the directives that generate doctree elements support the following options:

:class:text

Set a `"classes"`_ attribute value on the doctree element generated by the directive. See also the class_ directive.

:name:text

Add text to the `"names"`_ attribute of the doctree element generated by the directive. This allows `hyperlink references`_ to the element using text as `reference name`_.

Specifying the name option of a directive, e.g.,

.. image:: bild.png
   :name: my picture

is a concise syntax alternative to preceding it with a `hyperlink target`_

.. _my picture:

.. image:: bild.png

New in Docutils 0.8.

Last change: Tue, 03 Aug 2021 10:25 PM UTC