Admonitions¶

Admonitions, also known as call-outs, are an excellent choice for including side content without significantly interrupting the document flow. Zensical provides several different types of admonitions and allows for the inclusion and nesting of arbitrary content.

Configuration¶

This configuration enables admonitions, allows to make them collapsible and to nest arbitrary content inside admonitions. Add the following lines to your configuration:

[project.markdown_extensions]
admonition = {}
pymdownx.details = {}
pymdownx.superfences = {}

markdown_extensions:
  - admonition
  - pymdownx.details
  - pymdownx.superfences

See additional configuration options:

• Admonition
• Details
• SuperFences

Admonition icons¶

Each of the supported admonition types has a distinct icon, which can be changed to any icon bundled with the theme, or even a custom icon. Add the following lines to your configuration:

[project.theme.icon.admonition]
<type> = "<icon>"

[project.theme.icon.admonition]
note = "octicons/tag-16"
abstract = "octicons/checklist-16"
info = "octicons/info-16"
tip = "octicons/squirrel-16"
success = "octicons/check-16"
question = "octicons/question-16"
warning = "octicons/alert-16"
failure = "octicons/x-circle-16"
danger = "octicons/zap-16"
bug = "octicons/bug-16"
example = "octicons/beaker-16"
quote = "octicons/quote-16"

[project.theme.icon.admonition]
note = "fontawesome/solid/note-sticky"
abstract = "fontawesome/solid/book"
info = "fontawesome/solid/circle-info"
tip = "fontawesome/solid/bullhorn"
success = "fontawesome/solid/check"
question = "fontawesome/solid/circle-question"
warning = "fontawesome/solid/triangle-exclamation"
failure = "fontawesome/solid/bomb"
danger = "fontawesome/solid/skull"
bug = "fontawesome/solid/robot"
example = "fontawesome/solid/flask"
quote = "fontawesome/solid/quote-left"

theme:
  icon:
    admonition:
      <type>: <icon>

theme:
  icon:
    admonition:
      note: octicons/tag-16
      abstract: octicons/checklist-16
      info: octicons/info-16
      tip: octicons/squirrel-16
      success: octicons/check-16
      question: octicons/question-16
      warning: octicons/alert-16
      failure: octicons/x-circle-16
      danger: octicons/zap-16
      bug: octicons/bug-16
      example: octicons/beaker-16
      quote: octicons/quote-16

theme:
  icon:
    admonition:
      note: fontawesome/solid/note-sticky
      abstract: fontawesome/solid/book
      info: fontawesome/solid/circle-info
      tip: fontawesome/solid/bullhorn
      success: fontawesome/solid/check
      question: fontawesome/solid/circle-question
      warning: fontawesome/solid/triangle-exclamation
      failure: fontawesome/solid/bomb
      danger: fontawesome/solid/skull
      bug: fontawesome/solid/robot
      example: fontawesome/solid/flask
      quote: fontawesome/solid/quote-left

Usage¶

Admonitions follow a simple syntax: a block starts with !!!, followed by a single keyword used as a type qualifier. The content of the block follows on the next line, indented by four spaces:

!!! note

    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
    massa, nec semper lorem quam in massa.

Change the title¶

By default, the title will equal the type qualifier in titlecase. However, it can be changed by adding a quoted string containing valid Markdown (including links, formatting, ...) after the type qualifier:

!!! note "Phasellus posuere in sem ut cursus"

    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
    massa, nec semper lorem quam in massa.

Nested admonitions¶

You can also include nested admonitions in your documentation. To do this, you can use your existing admonitions and indent the desired ones:

!!! note "Outer Note"

    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
    massa, nec semper lorem quam in massa.

    !!! note "Inner Note"

        Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
        nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
        massa, nec semper lorem quam in massa.

Remove the title¶

Similar to changing the title, the icon and title can be omitted entirely by adding an empty string directly after the type qualifier. Note that this will not work for collapsible blocks:

!!! note ""

    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
    massa, nec semper lorem quam in massa.

Collapsible blocks¶

When Details is enabled and an admonition block is started with ??? instead of !!!, the admonition is rendered as an expandable block with a small toggle on the right side:

??? note

    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
    massa, nec semper lorem quam in massa.

Adding a + after the ??? token renders the block expanded:

???+ note

    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
    massa, nec semper lorem quam in massa.

Inline blocks¶

Admonitions can also be rendered as inline blocks (e.g., for sidebars), placing them to the right using the inline + end modifiers, or to the left using only the inline modifier:

!!! info inline end "Lorem ipsum"

    Lorem ipsum dolor sit amet, consectetur
    adipiscing elit. Nulla et euismod nulla.
    Curabitur feugiat, tortor non consequat
    finibus, justo purus auctor massa, nec
    semper lorem quam in massa.

!!! info inline "Lorem ipsum"

    Lorem ipsum dolor sit amet, consectetur
    adipiscing elit. Nulla et euismod nulla.
    Curabitur feugiat, tortor non consequat
    finibus, justo purus auctor massa, nec
    semper lorem quam in massa.

Important: admonitions that use the inline modifiers must be declared prior to the content block you want to place them beside. If there's insufficient space to render the admonition next to the block, the admonition will stretch to the full width of the viewport, e.g., on mobile viewports.

Supported types¶

The following admonition types are available in Zensical. The default is note.

note

Note

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

abstract

Abstract

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

info

Info

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

tip

Tip

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

success

Success

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

question

Question

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

warning

Warning

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

failure

Failure

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

danger

Danger

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

bug

Bug

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

example

Example

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

quote

Quote

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

GitHub callouts¶

In addition to the admonition syntax, GitHub callouts, also known as alerts, can be used. They are defined as blockquotes with a special marker. This syntax is portable to GitHub, GitLab, and other tools that recognize it.

Configuration¶

GitHub callouts are enabled with the Quotes extension, which is bundled with Python Markdown Extensions. The callouts option must be turned on in the configuration:

[project.markdown_extensions.pymdownx.quotes]
callouts = true

markdown_extensions:
  - pymdownx.quotes:
      callouts: true

Usage¶

A callout is started with a blockquote marker > followed by [!<type>]. The content of the callout follows on subsequent lines, each prefixed with >:

> [!NOTE]
> Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
> nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
> massa, nec semper lorem quam in massa.

The callout marker must be all uppercase. Lowercase markers, e.g. [!note], are not recognized by GitHub, so they are not rendered as callouts there.

Supported callout types¶

Five callout types are supported by GitHub. A direct mapping exists to the admonition types listed in the supported types section for three of them:

[!NOTE]

note

[!TIP]

tip

[!WARNING]

warning

[!IMPORTANT]

important – not a built-in admonition type, so the default admonition styling is used unless a custom style is added.

[!CAUTION]

caution – not a built-in admonition type, so the default admonition styling is used unless a custom style is added.

With the Quotes extension, any admonition type supported by Zensical can be used, not only these five.

Callouts are not part of the GitHub Flavored Markdown specification, so they are not supported by all GitHub Flavored Markdown parsers.