Admonitions

Admonitions, also known as call-outs, are an excellent choice for including side content without significantly interrupting the document flow:

Syntax¶

Admonitions are created using the following syntax:

/// admonition | Some title
    type: classname

Some content
///

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

/// admonition
    type: note

Some content.

More content.
///

will render as:

Optionally, you can use custom titles. For example:

/// admonition | Don't try this at home
    type: error

This is an admonition box
///

will render as:

If you don't want a title, leave it blank:

/// admonition |
    type: error

This is an admonition box without a title. It's not very fancy, is it?
///

results in:

Supported types¶

As a shortcut, there are a number of admonition blocks that can be used directly, like this:

/// note
This is a note
///

WriteADoc includes these default types: note, tip, warning, error, new, example, and question.

Collapsible admonitions (details)¶

If instead of admonition you use details, the admonition is rendered as a details/summary block with a small toggle on the right side:

/// details | Some summary
    type: warning

Some content
///

will render as:

If you wish to specify a details block as open (not collapsed), simply use the open option.

/// details | Some summary
    open: True

Some content
///

will render as:

Collapsible admonitions have the same predefined types as regular admonitions (note, tip, warning, error, new, example, and question), but unlike admonitions, details do not register any shortcut syntax by default.

This feature uses the pymdownx.blocks.details extension, and can be configured in the markdown options.

Inline admonitions¶

If the screen is wide enough, you can have inline admonitions, aligned to the left or right, by wrapping the content in a <div markdown="1"></div> tag and adding the "left" or "right" class to the admonition. Leave a blank line before and after the admonition.

<div markdown="1">

/// tip | Lorem Ipsum
    attrs: { class: left }

Lorem ipsum dolor sit amet, consectetur
adipiscing elit. Nulla et euismod nulla.
///

Some other content

</div>

<div markdown="1">

/// tip | Lorem Ipsum
    attrs: { class: right }

Lorem ipsum dolor sit amet, consectetur
adipiscing elit. Nulla et euismod nulla.
///

Some other content

</div>