2020-07-20 18:40:48 +03:00
|
|
|
---
|
|
|
|
|
template: overrides/main.html
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
# Admonitions
|
|
|
|
|
|
2020-07-21 14:33:44 +03:00
|
|
|
Admonitions, also known as _call-outs_, are an excellent choice for including
|
2020-07-20 20:28:13 +03:00
|
|
|
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.
|
2020-07-20 18:40:48 +03:00
|
|
|
|
|
|
|
|
## Configuration
|
|
|
|
|
|
|
|
|
|
### Admonition
|
|
|
|
|
|
|
|
|
|
[:octicons-file-code-24: Source][1] · [:octicons-workflow-24: Extension][2]
|
|
|
|
|
|
|
|
|
|
The [Admonition][2] extension, which is part of the standard Markdown
|
2020-07-23 14:17:50 +03:00
|
|
|
library, is integrated with Material for MkDocs and can be enabled via
|
2020-07-20 18:40:48 +03:00
|
|
|
`mkdocs.yml`:
|
|
|
|
|
|
|
|
|
|
``` yaml
|
|
|
|
|
markdown_extensions:
|
|
|
|
|
- admonition
|
|
|
|
|
```
|
|
|
|
|
|
2020-07-23 10:29:23 +03:00
|
|
|
[1]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/markdown/_admonition.scss
|
2020-07-20 18:40:48 +03:00
|
|
|
[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],
|
2020-07-23 14:17:50 +03:00
|
|
|
adds the ability to __make admonitions collapsible__. It can be enabled via
|
2020-07-20 18:40:48 +03:00
|
|
|
`mkdocs.yml`:
|
|
|
|
|
|
|
|
|
|
``` yaml
|
|
|
|
|
markdown_extensions:
|
|
|
|
|
- pymdownx.details
|
|
|
|
|
```
|
|
|
|
|
|
2020-07-23 10:29:23 +03:00
|
|
|
[3]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/pymdownx/_details.scss
|
2020-07-20 18:40:48 +03:00
|
|
|
[4]: https://facelessuser.github.io/pymdown-extensions/extensions/details/
|
|
|
|
|
[5]: https://facelessuser.github.io/pymdown-extensions/
|
|
|
|
|
|
|
|
|
|
### SuperFences
|
|
|
|
|
|
2020-07-23 16:34:43 +03:00
|
|
|
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:
|
2020-07-20 18:40:48 +03:00
|
|
|
|
|
|
|
|
``` yaml
|
|
|
|
|
markdown_extensions:
|
|
|
|
|
- pymdownx.superfences
|
|
|
|
|
```
|
2020-07-23 16:34:43 +03:00
|
|
|
[6]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/
|
2020-07-20 18:40:48 +03:00
|
|
|
|
|
|
|
|
## Usage
|
|
|
|
|
|
|
|
|
|
Admonitions follow a simple syntax: a block must start with `!!!`, followed
|
2020-07-23 16:34:43 +03:00
|
|
|
by a single keyword which is used as the [type qualifier][7] of the block. The
|
2020-07-20 18:40:48 +03:00
|
|
|
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.
|
|
|
|
|
|
2020-07-23 16:34:43 +03:00
|
|
|
[7]: #supported-types
|
2020-07-20 18:40:48 +03:00
|
|
|
|
|
|
|
|
### Changing the title
|
|
|
|
|
|
2020-07-21 14:33:44 +03:00
|
|
|
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.
|
2020-07-20 18:40:48 +03:00
|
|
|
|
|
|
|
|
_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
|
|
|
|
|
|
2020-07-23 16:34:43 +03:00
|
|
|
Similar to [changing the title][8], the icon and title can be omitted entirely
|
2020-07-21 14:33:44 +03:00
|
|
|
by adding an empty string directly after the type qualifier. Note that this
|
2020-07-23 16:34:43 +03:00
|
|
|
will not work for [collapsible blocks][9].
|
2020-07-20 18:40:48 +03:00
|
|
|
|
|
|
|
|
_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.
|
|
|
|
|
|
2020-07-23 16:34:43 +03:00
|
|
|
[8]: #changing-the-title
|
|
|
|
|
[9]: #collapsible-blocks
|
2020-07-20 18:40:48 +03:00
|
|
|
|
|
|
|
|
### 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
|
2020-07-23 16:34:43 +03:00
|
|
|
doesn't account for nested blocks, the [SuperFences][10] extension adds the
|
2020-07-21 14:33:44 +03:00
|
|
|
ability to nest arbitrary content inside admonitions.
|
2020-07-20 18:40:48 +03:00
|
|
|
|
|
|
|
|
_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.
|
|
|
|
|
|
2020-07-23 16:34:43 +03:00
|
|
|
[10]: #superfences
|
2020-07-20 18:40:48 +03:00
|
|
|
|
|
|
|
|
### Collapsible blocks
|
|
|
|
|
|
2020-07-23 16:34:43 +03:00
|
|
|
The [Details][11] extension adds support for rendering collapsible admonition
|
2020-07-20 18:40:48 +03:00
|
|
|
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.
|
|
|
|
|
|
2020-07-21 14:33:44 +03:00
|
|
|
Adding a `+` after `???` will render the block as open on page load:
|
2020-07-20 18:40:48 +03:00
|
|
|
|
|
|
|
|
_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.
|
|
|
|
|
|
2020-07-23 16:34:43 +03:00
|
|
|
[11]: #details
|
2020-07-20 18:40:48 +03:00
|
|
|
|
|
|
|
|
### 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`:
|
|
|
|
|
|
2020-07-23 16:34:43 +03:00
|
|
|
`note`{: #note }, `seealso`
|
2020-07-20 18:40:48 +03:00
|
|
|
|
|
|
|
|
: !!! 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.
|
|
|
|
|
|
2020-07-23 16:34:43 +03:00
|
|
|
`abstract`{: #abstract }, `summary`, `tldr`
|
2020-07-20 18:40:48 +03:00
|
|
|
|
|
|
|
|
: !!! 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.
|
|
|
|
|
|
2020-07-27 13:05:07 +03:00
|
|
|
`info`{: #info }, `todo`
|
2020-07-20 18:40:48 +03:00
|
|
|
|
|
|
|
|
: !!! 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.
|
|
|
|
|
|
2020-07-23 16:34:43 +03:00
|
|
|
`tip`{: #tip }, `hint`, `important`
|
2020-07-20 18:40:48 +03:00
|
|
|
|
|
|
|
|
: !!! 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.
|
|
|
|
|
|
2020-07-23 16:34:43 +03:00
|
|
|
`success`{: #success }, `check`, `done`
|
2020-07-20 18:40:48 +03:00
|
|
|
|
|
|
|
|
: !!! 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.
|
|
|
|
|
|
2020-07-23 16:34:43 +03:00
|
|
|
`question`{: #question }, `help`, `faq`
|
2020-07-20 18:40:48 +03:00
|
|
|
|
|
|
|
|
: !!! 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.
|
|
|
|
|
|
2020-07-23 16:34:43 +03:00
|
|
|
`warning`{: #warning }, `caution`, `attention`
|
2020-07-20 18:40:48 +03:00
|
|
|
|
|
|
|
|
: !!! 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.
|
|
|
|
|
|
2020-07-23 16:34:43 +03:00
|
|
|
`failure`{: #failure }, `fail`, `missing`
|
2020-07-20 18:40:48 +03:00
|
|
|
|
|
|
|
|
: !!! 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.
|
|
|
|
|
|
2020-07-23 16:34:43 +03:00
|
|
|
`danger`{: #danger }, `error`
|
2020-07-20 18:40:48 +03:00
|
|
|
|
|
|
|
|
: !!! 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.
|
|
|
|
|
|
2020-07-23 16:34:43 +03:00
|
|
|
`bug`{: #bug }
|
2020-07-20 18:40:48 +03:00
|
|
|
|
|
|
|
|
: !!! 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.
|
|
|
|
|
|
2020-07-23 16:34:43 +03:00
|
|
|
`example`{: #example }
|
2020-07-20 18:40:48 +03:00
|
|
|
|
|
|
|
|
: !!! 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.
|
|
|
|
|
|
2020-07-23 16:34:43 +03:00
|
|
|
`quote`{: #quote }, `cite`
|
2020-07-20 18:40:48 +03:00
|
|
|
|
|
|
|
|
: !!! 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.
|
