mkdocs-material/docs/extensions/admonition.md

457 lines
11 KiB
Markdown
Raw Normal View History

2016-09-02 23:59:14 +03:00
# Admonition
[Admonition][1] is an extension included in the standard Markdown library that
2020-03-09 21:03:48 +03:00
makes it possible to add block-styled side content to your documentation, e.g.
summaries, notes, hints or warnings.
2016-09-02 23:59:14 +03:00
[1]: https://python-markdown.github.io/extensions/admonition/
2020-03-09 21:03:48 +03:00
## Configuration
2020-03-09 21:03:48 +03:00
Add the following lines to `mkdocs.yml`:
``` yaml
markdown_extensions:
- admonition
```
## Usage
2020-03-09 21:03:48 +03:00
Admonitions follow a simple syntax: every block is started with `!!!`, followed
by a single keyword which is used as the [type qualifier][2] 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.
```
2016-09-02 23:59:14 +03:00
Result:
2016-09-02 23:59:14 +03:00
!!! note
2017-01-12 22:15:30 +03:00
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.
2016-09-02 23:59:14 +03:00
[2]: #types
### Changing the title
2020-03-09 21:03:48 +03:00
By default, the Admonition title will equal the type qualifier in titlecase.
However, it can be changed by adding a quoted string 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"
2017-01-12 22:15:30 +03:00
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-03-09 21:03:48 +03:00
Similar to [changing the title][3], the icon and title can be omitted by
providing an empty string after the type qualifier:
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:
2016-09-02 23:59:14 +03:00
!!! note ""
2017-01-12 22:15:30 +03:00
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.
[3]: #changing-the-title
2020-03-09 21:03:48 +03:00
### Embedded content
2020-03-09 21:03:48 +03:00
Admonitions can contain all kinds of text content, including headlines, lists,
paragraphs and other blocks except code blocks, because the parser from the
standard Markdown library does not account for those.
2020-03-09 21:03:48 +03:00
The [PyMdown Extensions][4] package adds an extension called [SuperFences][5],
which makes it possible to nest code blocks within other blocks, respectively
Admonition blocks.
[4]: https://facelessuser.github.io/pymdown-extensions
[5]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/
Example:
2016-09-02 23:59:14 +03:00
!!! note
2017-01-12 22:15:30 +03:00
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.
2016-09-02 23:59:14 +03:00
``` mysql
SELECT
Employees.EmployeeID,
Employees.Name,
Employees.Salary,
Manager.Name AS Manager
FROM
Employees
LEFT JOIN
Employees AS Manager
ON
Employees.ManagerID = Manager.EmployeeID
WHERE
Employees.EmployeeID = '087652';
```
2016-09-02 23:59:14 +03:00
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.
### Collapsible blocks
The [Details][6] extension which is also part of the [PyMdown Extensions][4]
package adds support for rendering collapsible Admonition blocks. This is
useful for FAQs or content that is of secondary nature.
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.
By adding a `+` sign directly after the start marker, blocks can be rendered
open by default.
[6]: https://facelessuser.github.io/pymdown-extensions/extensions/details/
## Types
Admonition supports user-defined type qualifiers which may influence the style
2020-03-09 21:03:48 +03:00
of the inserted block. 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
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
2017-01-12 22:15:30 +03:00
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.
Qualifiers:
* `note`
* `seealso`
2018-01-10 00:53:56 +03:00
### Abstract
Example:
``` markdown
2018-01-10 00:53:56 +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.
```
Result:
2018-01-10 00:53:56 +03:00
!!! abstract
2017-01-12 22:15:30 +03:00
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.
Qualifiers:
2018-01-10 00:53:56 +03:00
* `abstract`
* `summary`
* `tldr`
### Info
Example:
``` markdown
!!! 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.
```
Result:
!!! 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.
Qualifiers:
* `info`
* `todo`
### Tip
Example:
``` markdown
!!! 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.
```
Result:
!!! tip
2017-01-12 22:15:30 +03:00
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.
Qualifiers:
* `tip`
* `hint`
* `important`
### Success
Example:
``` markdown
!!! 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.
```
Result:
!!! success
2017-01-12 22:15:30 +03:00
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.
Qualifiers:
* `success`
* `check`
* `done`
### Question
Example:
``` markdown
!!! 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.
```
Result:
!!! 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.
Qualifiers:
* `question`
* `help`
* `faq`
### Warning
Example:
``` markdown
!!! 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.
```
Result:
!!! warning
2017-01-12 22:15:30 +03:00
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.
Qualifiers:
* `warning`
* `caution`
* `attention`
### Failure
Example:
``` markdown
!!! 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.
```
Result:
!!! failure
2017-01-12 22:15:30 +03:00
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.
Qualifiers:
* `failure`
* `fail`
* `missing`
### Danger
Example:
``` markdown
!!! 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.
```
Result:
!!! danger
2017-01-12 22:15:30 +03:00
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.
Qualifiers:
2016-09-02 23:59:14 +03:00
* `danger`
* `error`
2016-09-02 23:59:14 +03:00
### Bug
2016-09-02 23:59:14 +03:00
Example:
2016-09-23 12:56:25 +03:00
``` markdown
!!! 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.
```
2016-09-02 23:59:14 +03:00
Result:
2016-09-02 23:59:14 +03:00
!!! bug
2017-01-12 22:15:30 +03:00
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.
2016-09-02 23:59:14 +03:00
Qualifiers:
2016-09-02 23:59:14 +03:00
* `bug`
2017-02-26 21:50:53 +03:00
2018-01-10 00:53:56 +03:00
### Example
Example:
``` markdown
!!! 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.
```
Result:
!!! 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.
Qualifiers:
* `example`
* `snippet`
2017-02-26 21:50:53 +03:00
### Quote
Example:
``` markdown
!!! 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.
```
Result:
!!! 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.
Qualifiers:
* `quote`
* `cite`