Admonition¶

Summary¶

The Admonition extension adds rST-style admonitions to Markdown documents.

This extension is included in the standard Markdown library.

Syntax¶

Admonitions are created using the following syntax:

!!! type "optional explicit title within double quotes"
    Any number of other indented markdown elements.

    This is the second paragraph.

type will be used as the CSS class name and as default title. It must be a single word. So, for instance:

!!! note
    You should note that the title will be automatically capitalized.

will render:

<div class="admonition note">
<p class="admonition-title">Note</p>
<p>You should note that the title will be automatically capitalized.</p>
</div>

Optionally, you can use custom titles. For instance:

!!! danger "Don't try this at home"
    ...

will render:

<div class="admonition danger">
<p class="admonition-title">Don't try this at home</p>
<p>...</p>
</div>

If you don’t want a title, use a blank string "":

!!! important ""
    This is an admonition box without a title.

results in:

<div class="admonition important">
<p>This is an admonition box without a title.</p>
</div>

You can also provide additional CSS class names separated by spaces. The first class should be the “type.” For example:

!!! danger highlight blink "Don't try this at home"
    ...

will render:

<div class="admonition danger highlight blink">
<p class="admonition-title">Don't try this at home</p>
<p>...</p>
</div>

rST suggests the following “types”: attention, caution, danger, error, hint, important, note, tip, and warning; however, you’re free to use whatever you want.

Styling¶

There is no CSS included as part of this extension. Check out the default Sphinx theme for inspiration.

Usage¶

See Extensions for general extension usage. Use admonition as the name of the extension.

This extension does not accept any special configuration options.

A trivial example:

markdown.markdown(some_text, extensions=['admonition'])