diff --git a/docs/reference/admonitions.md b/docs/reference/admonitions.md index 239cc43cd..a1895f4d0 100644 --- a/docs/reference/admonitions.md +++ b/docs/reference/admonitions.md @@ -11,61 +11,38 @@ 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`: +The following configuration enables admonitions, allows to make them collapsible +and to nest arbitrary content inside admonition bodies. Add the following lines +to `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/ + +See additional configuration options: + +- [Admonition] +- [Details] +- [SuperFences] + + [Admonition]: ../setup/extensions/python-markdown.md#admonition + [Details]: ../setup/extensions/python-markdown-extensions.md#details + [SuperFences]: ../setup/extensions/python-markdown-extensions.md#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. +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. _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. @@ -79,7 +56,7 @@ _Result_: nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa. - [7]: #supported-types + [type qualifier]: #supported-types ### Changing the title @@ -91,6 +68,7 @@ _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. @@ -106,14 +84,15 @@ _Result_: ### 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]. +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]. _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. @@ -127,70 +106,20 @@ _Result_: 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 + [changing the title]: #changing-the-title + [collapsible blocks]: #collapsible-blocks ### 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 `???`. +If the [Details] extension is enabled and an admonition is started with `???` +instead of `!!!`, the admonition is rendered as a collapsible block with a +small marker on the right side. _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. @@ -204,12 +133,13 @@ _Result_: 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: +Adding a `+` after the `???` token will render the block as open. _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. @@ -223,23 +153,13 @@ _Result_: 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 can also be rendered as inline blocks (i.e. for sidebars), placing +them to the right using the `inline` + `end` modifiers, or to the left using +only the `inline` modifier. -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" +=== ":octicons-arrow-right-16: inline end" _Example_ / _Result_: @@ -251,6 +171,7 @@ will stretch to the full width of the viewport, e.g. on mobile viewports. ``` markdown !!! info inline end + Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat @@ -260,7 +181,7 @@ will stretch to the full width of the viewport, e.g. on mobile viewports. Use `inline end` to align to the right (left for rtl languages). -=== "inline" +=== ":octicons-arrow-left-16: inline" _Example_ / _Result_: @@ -272,6 +193,7 @@ will stretch to the full width of the viewport, e.g. on mobile viewports. ``` markdown !!! info inline + Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat @@ -281,7 +203,10 @@ will stretch to the full width of the viewport, e.g. on mobile viewports. 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 +__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 @@ -389,18 +314,17 @@ the default type, and thus fallback for unknown type qualifiers, is `note`: 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. + in :octicons-tag-24: 7.1.5 and will be removed in :octicons-tag-24: 8.0.0. ### Changing the icons -[:octicons-file-code-24: Source][13] · -[:octicons-heart-fill-24:{ .mdx-heart } Insiders only][13]{ .mdx-insiders } +> This feature is currently only available in [:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .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" +=== ":octicons-mark-github-16: Octicons" _Example_: @@ -424,10 +348,10 @@ a valid icon in `mkdocs.yml`: _Result_: - [![Admonition with Octicons icons][14]][14] + [![Admonition with Octicons icons][Octicons]][Octicons] -=== "FontAwesome" +=== ":fontawesome-brands-font-awesome: FontAwesome" _Example_: @@ -451,19 +375,19 @@ a valid icon in `mkdocs.yml`: _Result_: - [![Admonition with FontAwesome icons][15]][15] + [![Admonition with FontAwesome icons][FontAwesome]][FontAwesome] - [13]: ../insiders/index.md - [14]: ../assets/screenshots/admonition-octicons.png - [15]: ../assets/screenshots/admonition-fontawesome.png + [Insiders]: ../insiders/index.md + [Octicons]: ../assets/screenshots/admonition-octicons.png + [FontAwesome]: ../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]: +`*.svg` icon. Copy the icon's code from the [`.icons`][Custom icons] folder +and add the following CSS to an [additional stylesheet]: ``` css :root { @@ -488,7 +412,7 @@ following CSS to an [additional stylesheet][17]: 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]. +colors. [You can even add animations][Custom animations].