admonitions

admonitions extra

Added in version 2.4.3, the admonitions extra adds support for ReST admonitions. Taken from the ReST directives documentation:

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.

Syntax

The general syntax is as follows:

.. [TYPE]:: [Optional title]
   [Body, indented by 3 spaces or more]

The allowed admonition types are defined here.

Examples

.. NOTE:: Admonitions
   They contain 3 main parts, the admonition type (the bit before the "::"),
   title (the bit after the "::") and body (the text underneath).  

   The admonition type is case insensitive, title is optional and the body
   should be able to contain pretty much anything. For example:

   - Lists
   - With multiple levels
     - Of indentation

   And code blocks:

       print('indented code blocks')

.. warning::
   The admonition's body must be indented by a tab or 3 or more spaces
   from where the admonition was declared
  This line is indented by only 2 spaces, and so isn't part of the admonition.

.. IMPORTANT::
   You can also use 3 or more empty lines after an admonition  
   to end it



    print('In case you wanted something like')
    print('an indented code block right after')

.. admonition:: Generic admonitions

   These should be given a title but this is not enforced

   .. note:: Nested admonitions
      Nested admonitions should also work

      - Even inside
        .. tip::
           of a list

Module usage

markdown2.markdown(your_text, extras=['admonitions'])

Command line usage

python lib/markdown2.py -x admonitions foo.txt

Resulting HTML

.. warning:: Deprecated
   Feature XYZ was deprecated in version 1.2.3

.. info::
   Without a title

The above admonition will look something like this:

<aside class="admonition warning">
    <strong>warning</strong>
    <em>Deprecated</em>
    <p>Feature XYZ was deprecated in version 1.2.3</p>
</aside>

<aside class="admonition info">
    <strong>info</strong>
    <p>Without a title</p>
</aside>