admonition¶
admonition is reStructuredText’s so-called generic admonition. It is visually bold block often rendered in neutral colors. Unlike specific admonitions like danger, note, or tip, generic admonition has a title and usually neutral appearance.
Requires title and content¶
admonition has strict syntax. You need to pass a title after admonition:: (note the space after ::), and a content bellow the blank line.
1.. admonition:: Generic admonitions has a title
2
3 A content follows under the blank line.
Generic admonitions has a title
A content follows under the blank line.
All the following variants are invalid:
1.. admonition:: title
1.. admonition::
2 content
1.. admonition::
2
3 content
1.. admonition:: title
2 content
Directive name in uppercase¶
Directive name is case insensitive (like all directive and role names). Most documentation and book authors prefer typing directives and roles all in lowercase. However, writing directive name in uppercase corresponds with their “raise attention” objective and improves reStructuredText code readability.
1.. ADMONITION:: Uppercase title
2
3 However writing admonitions uppercase can be considered as reasonable exception to "all-lowercase" rule.
Uppercase title
However writing admonitions uppercase can be considered as reasonable exception to “all-lowercase” rule.
Complex content¶
Any reStructuredText elements can be in admonition content. As always, you need only to keep correct indentation.
1.. admonition:: Complex content
2
3 This is the admonition with complex body containing
4
5 - two items
6 - bullet list
7
8 And, code example::
9
10 $ nano ~/.bash_aliases
Complex content
This is the admonition with complex body containing
two items
bullet list
And, code example:
$ nano ~/.bash_aliases
Previous: Sphinx additions | Next: attention