Admonition¶

Summary¶

The Admonition extension addsrST-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 asingle 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 firstclass 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, andwarning; however, you’re free to usewhatever you want.

Styling¶

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

Usage¶

SeeExtensions for general extension usage. Useadmonition as thename of the extension.

This extension does not accept any special configuration options.

A trivial example:

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