--- template: overrides/main.html --- # Admonitions Admonitions, also known as _call-outs_, are an excellent choice for including side content without significantly interrupting the document flow. Material for MkDocs provides several different types of admonitions and allows for the inclusion and nesting of arbitrary content. ## Configuration ### Admonition [:octicons-file-code-24: Source][1] · [:octicons-workflow-24: Extension][2] The [Admonition][2] extension, which is part of the standard Markdown library, is integrated with Material for MkDocs and can be enabled via `mkdocs.yml`: ``` yaml markdown_extensions: - admonition ``` [1]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/markdown/_admonition.scss [2]: https://python-markdown.github.io/extensions/admonition/ ### Details [:octicons-file-code-24: Source][3] · [:octicons-workflow-24: Extension][4] The [Details][4] extension, which is part of [Python Markdown Extensions][5], adds the ability to __make admonitions collapsible__. It can be enabled via `mkdocs.yml`: ``` yaml markdown_extensions: - pymdownx.details ``` [3]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/pymdownx/_details.scss [4]: https://facelessuser.github.io/pymdown-extensions/extensions/details/ [5]: https://facelessuser.github.io/pymdown-extensions/ ### SuperFences The [SuperFences][6] extension, which is also part of [Python Markdown Extensions][5], allows for the __nesting of code and content blocks inside admonitions__, and is therefore strongly recommended: ``` yaml markdown_extensions: - pymdownx.superfences ``` [6]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/ ## Usage Admonitions follow a simple syntax: a block must start with `!!!`, followed by a single keyword which is used as the [type qualifier][7] of the block. The content of the block then follows on the next line, indented by four spaces. _Example_: ``` markdown !!! 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. ``` _Result_: !!! 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. [7]: #supported-types ### Changing 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. _Example_: ``` markdown !!! 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. ``` _Result_: !!! 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. ### Removing the title Similar to [changing the title][8], 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][9]. _Example_: ``` markdown !!! 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. ``` _Result_: !!! 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. [8]: #changing-the-title [9]: #collapsible-blocks ### Embedded content Admonitions can contain all kinds of text content, including headlines, lists, paragraphs and other blocks. While the parser from the standard Markdown library doesn't account for nested blocks, the [SuperFences][10] extension adds the ability to nest arbitrary content inside admonitions. _Example_: ``` markdown !!! 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. ``` python def bubble_sort(items): for i in range(len(items)): for j in range(len(items) - 1 - i): if items[j] > items[j + 1]: items[j], items[j + 1] = items[j + 1], items[j] ``` Nunc eu odio eleifend, blandit leo a, volutpat sapien. Phasellus posuere in sem ut cursus. Nullam sit amet tincidunt ipsum, sit amet elementum turpis. Etiam ipsum quam, mattis in purus vitae, lacinia fermentum enim. ``` _Result_: !!! 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. ``` python def bubble_sort(items): for i in range(len(items)): for j in range(len(items) - 1 - i): if items[j] > items[j + 1]: items[j], items[j + 1] = items[j + 1], items[j] ``` Nunc eu odio eleifend, blandit leo a, volutpat sapien. Phasellus posuere in sem ut cursus. Nullam sit amet tincidunt ipsum, sit amet elementum turpis. Etiam ipsum quam, mattis in purus vitae, lacinia fermentum enim. [10]: #superfences ### Collapsible blocks The [Details][11] extension adds support for rendering collapsible admonition blocks. This is useful for FAQs or content that is of secondary nature. A details block follows the syntax and semantics of admonition blocks, but must start with `???`. _Example_: ``` markdown ??? 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. ``` _Result_: ??? 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 `???` will render the block as open on page load: _Example_: ``` markdown ???+ 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. ``` _Result_: ???+ 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. [11]: #details ### Inline blocks [:octicons-file-code-24: Source][12] · :octicons-beaker-24: Experimental Admonitions and [Details][11] can also be rendered as inline blocks (i.e. sidebars), placing them to the right using the `inline` + `end` modifiers, or to the left using only the `inline` modifier. __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. === "inline end" _Example_ / _Result_: !!! info inline end 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. ``` markdown !!! info inline end 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. ``` Use `inline end` to align to the right (left for rtl languages). === "inline" _Example_ / _Result_: !!! info inline 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. ``` markdown !!! info inline 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. ``` Use `inline` to align to the left (right for rtl languages). [12]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/_modifiers.scss ### Supported types Following is a list of type qualifiers provided by Material for MkDocs, whereas the default type, and thus fallback for unknown type qualifiers, is `note`: `note`{ #note }, ~~`seealso`~~ [^1] : !!! 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 }, `summary`, `tldr` : !!! 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 }, `todo` : !!! 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 }, `hint`, `important` : !!! 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 }, `check`, `done` : !!! 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 }, `help`, `faq` : !!! 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 }, `caution`, `attention` : !!! 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 }, `fail`, `missing` : !!! 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 }, `error` : !!! 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 } : !!! 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 } : !!! 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 }, `cite` : !!! 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. [^1]: The `seealso` qualifier was originally adapted from the `readthedocs` theme, in order to make it easier for authors to migrate to Material for MkDocs. However, when the title is omitted, the admonition extension will render it as `Seealso`, which is incorrect English. For this reason, it was deprecated as of 7.1.5 and will be removed in 8.x. ### Changing the icons [:octicons-file-code-24: Source][13] · [:octicons-heart-fill-24:{ .mdx-heart } Insiders only][13]{ .mdx-insiders } Each of the supported admonition types has a distinct icon, which can be changed to any icon bundled with the theme. Just set the name of the admonition type to a valid icon in `mkdocs.yml`: === "Octicons" _Example_: ``` yaml 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 ``` _Result_: [![Admonition with Octicons icons][14]][14] === "FontAwesome" _Example_: ``` yaml theme: icon: admonition: note: fontawesome/solid/sticky-note abstract: fontawesome/solid/book info: fontawesome/solid/info-circle tip: fontawesome/solid/bullhorn success: fontawesome/solid/check question: fontawesome/solid/question-circle warning: fontawesome/solid/exclamation-triangle failure: fontawesome/solid/bomb danger: fontawesome/solid/skull bug: fontawesome/solid/robot example: fontawesome/solid/flask quote: fontawesome/solid/quote-left ``` _Result_: [![Admonition with FontAwesome icons][15]][15] [13]: ../insiders/index.md [14]: ../assets/screenshots/admonition-octicons.png [15]: ../assets/screenshots/admonition-fontawesome.png ## Customization ### Custom admonitions If you want to add a custom admonition type, all you need is a color and an `svg` icon. Copy the icon's `svg` code from the [`.icons`][16] folder and add the following CSS to an [additional stylesheet][17]: ``` css :root { --md-admonition-icon--pied-piper: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 576 512"><path d="M244 246c-3.2-2-6.3-2.9-10.1-2.9-6.6 0-12.6 3.2-19.3 3.7l1.7 4.9zm135.9 197.9c-19 0-64.1 9.5-79.9 19.8l6.9 45.1c35.7 6.1 70.1 3.6 106-9.8-4.8-10-23.5-55.1-33-55.1zM340.8 177c6.6 2.8 11.5 9.2 22.7 22.1 2-1.4 7.5-5.2 7.5-8.6 0-4.9-11.8-13.2-13.2-23 11.2-5.7 25.2-6 37.6-8.9 68.1-16.4 116.3-52.9 146.8-116.7C548.3 29.3 554 16.1 554.6 2l-2 2.6c-28.4 50-33 63.2-81.3 100-31.9 24.4-69.2 40.2-106.6 54.6l-6.3-.3v-21.8c-19.6 1.6-19.7-14.6-31.6-23-18.7 20.6-31.6 40.8-58.9 51.1-12.7 4.8-19.6 10-25.9 21.8 34.9-16.4 91.2-13.5 98.8-10zM555.5 0l-.6 1.1-.3.9.6-.6zm-59.2 382.1c-33.9-56.9-75.3-118.4-150-115.5l-.3-6c-1.1-13.5 32.8 3.2 35.1-31l-14.4 7.2c-19.8-45.7-8.6-54.3-65.5-54.3-14.7 0-26.7 1.7-41.4 4.6 2.9 18.6 2.2 36.7-10.9 50.3l19.5 5.5c-1.7 3.2-2.9 6.3-2.9 9.8 0 21 42.8 2.9 42.8 33.6 0 18.4-36.8 60.1-54.9 60.1-8 0-53.7-50-53.4-60.1l.3-4.6 52.3-11.5c13-2.6 12.3-22.7-2.9-22.7-3.7 0-43.1 9.2-49.4 10.6-2-5.2-7.5-14.1-13.8-14.1-3.2 0-6.3 3.2-9.5 4-9.2 2.6-31 2.9-21.5 20.1L15.9 298.5c-5.5 1.1-8.9 6.3-8.9 11.8 0 6 5.5 10.9 11.5 10.9 8 0 131.3-28.4 147.4-32.2 2.6 3.2 4.6 6.3 7.8 8.6 20.1 14.4 59.8 85.9 76.4 85.9 24.1 0 58-22.4 71.3-41.9 3.2-4.3 6.9-7.5 12.4-6.9.6 13.8-31.6 34.2-33 43.7-1.4 10.2-1 35.2-.3 41.1 26.7 8.1 52-3.6 77.9-2.9 4.3-21 10.6-41.9 9.8-63.5l-.3-9.5c-1.4-34.2-10.9-38.5-34.8-58.6-1.1-1.1-2.6-2.6-3.7-4 2.2-1.4 1.1-1 4.6-1.7 88.5 0 56.3 183.6 111.5 229.9 33.1-15 72.5-27.9 103.5-47.2-29-25.6-52.6-45.7-72.7-79.9zm-196.2 46.1v27.2l11.8-3.4-2.9-23.8zm-68.7-150.4l24.1 61.2 21-13.8-31.3-50.9zm84.4 154.9l2 12.4c9-1.5 58.4-6.6 58.4-14.1 0-1.4-.6-3.2-.9-4.6-26.8 0-36.9 3.8-59.5 6.3z"/></svg>') } .md-typeset .admonition.pied-piper, .md-typeset details.pied-piper { border-color: rgb(43, 155, 70); } .md-typeset .pied-piper > .admonition-title, .md-typeset .pied-piper > summary { background-color: rgba(43, 155, 70, 0.1); border-color: rgb(43, 155, 70); } .md-typeset .pied-piper > .admonition-title::before, .md-typeset .pied-piper > summary::before { background-color: rgb(43, 155, 70); -webkit-mask-image: var(--md-admonition-icon--pied-piper); mask-image: var(--md-admonition-icon--pied-piper); } ``` You should now be able to create an admonition of the `pied-piper` type. Note that you can also use this technique to override existing admonition icons or colors. [You can even add animations][18]. <style> :root { --md-admonition-icon--pied-piper: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 576 512"><path d="M244 246c-3.2-2-6.3-2.9-10.1-2.9-6.6 0-12.6 3.2-19.3 3.7l1.7 4.9zm135.9 197.9c-19 0-64.1 9.5-79.9 19.8l6.9 45.1c35.7 6.1 70.1 3.6 106-9.8-4.8-10-23.5-55.1-33-55.1zM340.8 177c6.6 2.8 11.5 9.2 22.7 22.1 2-1.4 7.5-5.2 7.5-8.6 0-4.9-11.8-13.2-13.2-23 11.2-5.7 25.2-6 37.6-8.9 68.1-16.4 116.3-52.9 146.8-116.7C548.3 29.3 554 16.1 554.6 2l-2 2.6c-28.4 50-33 63.2-81.3 100-31.9 24.4-69.2 40.2-106.6 54.6l-6.3-.3v-21.8c-19.6 1.6-19.7-14.6-31.6-23-18.7 20.6-31.6 40.8-58.9 51.1-12.7 4.8-19.6 10-25.9 21.8 34.9-16.4 91.2-13.5 98.8-10zM555.5 0l-.6 1.1-.3.9.6-.6zm-59.2 382.1c-33.9-56.9-75.3-118.4-150-115.5l-.3-6c-1.1-13.5 32.8 3.2 35.1-31l-14.4 7.2c-19.8-45.7-8.6-54.3-65.5-54.3-14.7 0-26.7 1.7-41.4 4.6 2.9 18.6 2.2 36.7-10.9 50.3l19.5 5.5c-1.7 3.2-2.9 6.3-2.9 9.8 0 21 42.8 2.9 42.8 33.6 0 18.4-36.8 60.1-54.9 60.1-8 0-53.7-50-53.4-60.1l.3-4.6 52.3-11.5c13-2.6 12.3-22.7-2.9-22.7-3.7 0-43.1 9.2-49.4 10.6-2-5.2-7.5-14.1-13.8-14.1-3.2 0-6.3 3.2-9.5 4-9.2 2.6-31 2.9-21.5 20.1L15.9 298.5c-5.5 1.1-8.9 6.3-8.9 11.8 0 6 5.5 10.9 11.5 10.9 8 0 131.3-28.4 147.4-32.2 2.6 3.2 4.6 6.3 7.8 8.6 20.1 14.4 59.8 85.9 76.4 85.9 24.1 0 58-22.4 71.3-41.9 3.2-4.3 6.9-7.5 12.4-6.9.6 13.8-31.6 34.2-33 43.7-1.4 10.2-1 35.2-.3 41.1 26.7 8.1 52-3.6 77.9-2.9 4.3-21 10.6-41.9 9.8-63.5l-.3-9.5c-1.4-34.2-10.9-38.5-34.8-58.6-1.1-1.1-2.6-2.6-3.7-4 2.2-1.4 1.1-1 4.6-1.7 88.5 0 56.3 183.6 111.5 229.9 33.1-15 72.5-27.9 103.5-47.2-29-25.6-52.6-45.7-72.7-79.9zm-196.2 46.1v27.2l11.8-3.4-2.9-23.8zm-68.7-150.4l24.1 61.2 21-13.8-31.3-50.9zm84.4 154.9l2 12.4c9-1.5 58.4-6.6 58.4-14.1 0-1.4-.6-3.2-.9-4.6-26.8 0-36.9 3.8-59.5 6.3z"/></svg>') } .md-typeset .admonition.pied-piper, .md-typeset details.pied-piper { border-color: rgb(43, 155, 70); } .md-typeset .pied-piper > .admonition-title, .md-typeset .pied-piper > summary { background-color: rgba(43, 155, 70, 0.1); border-color: rgb(43, 155, 70); } .md-typeset .pied-piper > .admonition-title::before, .md-typeset .pied-piper > summary::before { background-color: rgb(43, 155, 70); -webkit-mask-image: var(--md-admonition-icon--pied-piper); mask-image: var(--md-admonition-icon--pied-piper); } </style> _Example_: ``` markdown !!! pied-piper "Pied Piper" 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. ``` _Result_: !!! pied-piper "Pied Piper" 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. [16]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons [17]: ../customization.md#additional-css [18]: icons-emojis.md#with-animations