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:

zensical.tomlmkdocs.yml

[project.markdown_extensions.admonition]
[project.markdown_extensions.pymdownx.details]
[project.markdown_extensions.pymdownx.superfences]

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

See additional configuration options:

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 mkdocs.yml:

zensical.tomlmkdocs.yml

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

Expand to show alternate icon sets

Octicons FontAwesome

[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>

Expand to show alternate icon sets

Octicons FontAwesome

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:

Admonition

!!! 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