2016-09-02 22:59:14 +02:00
|
|
|
|
# Admonition
|
|
|
|
|
|
|
2016-12-18 13:29:03 +01:00
|
|
|
|
[Admonition][1] is an extension included in the standard Markdown library that
|
2016-10-21 21:15:35 +02:00
|
|
|
|
makes it possible to add block-styled side content to your documentation, for
|
2017-01-05 08:31:58 +01:00
|
|
|
|
example summaries, notes, hints or warnings.
|
2016-09-02 22:59:14 +02:00
|
|
|
|
|
2016-12-18 13:29:03 +01:00
|
|
|
|
[1]: https://pythonhosted.org/Markdown/extensions/admonition.html
|
|
|
|
|
|
|
2016-10-21 21:15:35 +02:00
|
|
|
|
## Installation
|
|
|
|
|
|
|
|
|
|
|
|
Add the following lines to your `mkdocs.yml`:
|
|
|
|
|
|
|
|
|
|
|
|
``` yaml
|
|
|
|
|
|
markdown_extensions:
|
|
|
|
|
|
- admonition
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
## Usage
|
|
|
|
|
|
|
|
|
|
|
|
Admonition blocks follow a simple syntax: every block is started with `!!!`,
|
|
|
|
|
|
followed by a single keyword which is used as the [type qualifier](#types) of
|
|
|
|
|
|
the block. The content of the block then follows on the next line, indented by
|
|
|
|
|
|
four spaces.
|
|
|
|
|
|
|
|
|
|
|
|
Example:
|
|
|
|
|
|
|
|
|
|
|
|
``` markdown
|
2017-01-05 08:31:58 +01:00
|
|
|
|
!!! note
|
2016-10-21 21:15:35 +02: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 22:59:14 +02:00
|
|
|
|
|
2016-10-21 21:15:35 +02:00
|
|
|
|
Result:
|
2016-09-02 22:59:14 +02:00
|
|
|
|
|
2017-01-05 08:31:58 +01:00
|
|
|
|
!!! note
|
2016-10-21 21:15:35 +02: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 22:59:14 +02:00
|
|
|
|
|
2016-10-30 10:36:18 +01:00
|
|
|
|
### Changing the title
|
2016-10-21 21:15:35 +02:00
|
|
|
|
|
|
|
|
|
|
By default, the block title will equal the type qualifier. However, it can
|
|
|
|
|
|
easily be changed by adding a quoted string after the type qualifier.
|
|
|
|
|
|
|
|
|
|
|
|
Example:
|
|
|
|
|
|
|
|
|
|
|
|
``` markdown
|
2017-01-05 08:31:58 +01:00
|
|
|
|
!!! note "Phasellus posuere in sem ut cursus"
|
2016-10-21 21:15:35 +02: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.
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
Result:
|
|
|
|
|
|
|
2017-01-05 08:31:58 +01:00
|
|
|
|
!!! note "Phasellus posuere in sem ut cursus"
|
2016-10-21 21:15:35 +02: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-10-30 10:36:18 +01:00
|
|
|
|
### Removing the title
|
2016-10-21 21:15:35 +02:00
|
|
|
|
|
2016-10-30 10:36:18 +01:00
|
|
|
|
Similar to setting a [custom title](#changing-the-title), the icon and title
|
|
|
|
|
|
can be omitted by providing an empty string after the type qualifier:
|
2016-10-21 21:15:35 +02:00
|
|
|
|
|
|
|
|
|
|
Example:
|
|
|
|
|
|
|
|
|
|
|
|
``` markdown
|
2017-01-05 08:31:58 +01:00
|
|
|
|
!!! note ""
|
2016-10-21 21:15:35 +02: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.
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
Result:
|
2016-09-02 22:59:14 +02:00
|
|
|
|
|
2017-01-05 08:31:58 +01:00
|
|
|
|
!!! note ""
|
2016-10-21 21:15:35 +02: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.
|
|
|
|
|
|
|
|
|
|
|
|
### Embedded code blocks
|
|
|
|
|
|
|
|
|
|
|
|
Blocks 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.
|
|
|
|
|
|
|
2016-12-18 13:29:03 +01:00
|
|
|
|
However, the [PyMdown Extensions][2] package adds an extension called
|
|
|
|
|
|
[SuperFences][3], which makes it possible to nest code blocks within other
|
2016-12-15 15:55:40 +01:00
|
|
|
|
blocks.
|
2016-10-21 21:15:35 +02:00
|
|
|
|
|
2016-12-18 13:29:03 +01:00
|
|
|
|
[2]: https://facelessuser.github.io/pymdown-extensions
|
|
|
|
|
|
[3]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/
|
|
|
|
|
|
|
2016-10-21 21:15:35 +02:00
|
|
|
|
Example:
|
2016-09-02 22:59:14 +02:00
|
|
|
|
|
2017-01-05 08:31:58 +01:00
|
|
|
|
!!! note
|
2016-10-21 21:15:35 +02: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 22:59:14 +02:00
|
|
|
|
|
2016-10-21 21:15:35 +02: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 22:59:14 +02: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.
|
|
|
|
|
|
|
2016-10-21 21:15:35 +02:00
|
|
|
|
## Types
|
|
|
|
|
|
|
|
|
|
|
|
Admonition supports user-defined type qualifiers which may influence the style
|
|
|
|
|
|
of the inserted block. Following is a list of type qualifiers supported by the
|
|
|
|
|
|
Material theme, whereas the default type, and thus fallback for unknown type
|
2017-01-05 08:31:58 +01:00
|
|
|
|
qualifiers, is [note](#note).
|
2016-10-21 21:15:35 +02:00
|
|
|
|
|
2017-01-05 08:31:58 +01:00
|
|
|
|
### Note
|
2016-10-21 21:15:35 +02:00
|
|
|
|
|
|
|
|
|
|
Example:
|
|
|
|
|
|
|
|
|
|
|
|
``` markdown
|
2017-01-05 08:31:58 +01:00
|
|
|
|
!!! note
|
2016-10-21 21:15:35 +02: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.
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
Result:
|
|
|
|
|
|
|
2017-01-05 08:31:58 +01:00
|
|
|
|
!!! note
|
2016-10-21 21:15:35 +02: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`
|
2017-01-05 08:31:58 +01:00
|
|
|
|
* `seealso`
|
2016-10-21 21:15:35 +02:00
|
|
|
|
|
|
|
|
|
|
### Summary
|
|
|
|
|
|
|
|
|
|
|
|
Example:
|
|
|
|
|
|
|
|
|
|
|
|
``` markdown
|
|
|
|
|
|
!!! summary
|
|
|
|
|
|
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:
|
|
|
|
|
|
|
|
|
|
|
|
!!! summary
|
|
|
|
|
|
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:
|
|
|
|
|
|
|
|
|
|
|
|
* `summary`
|
|
|
|
|
|
* `tldr`
|
|
|
|
|
|
|
|
|
|
|
|
### 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
|
|
|
|
|
|
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`
|
2017-01-05 08:31:58 +01:00
|
|
|
|
* `hint`
|
|
|
|
|
|
* `important`
|
2016-10-21 21:15:35 +02:00
|
|
|
|
|
|
|
|
|
|
### 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
|
|
|
|
|
|
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`
|
|
|
|
|
|
|
|
|
|
|
|
### 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
|
|
|
|
|
|
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`
|
2017-01-05 08:31:58 +01:00
|
|
|
|
* `caution`
|
2016-10-21 21:15:35 +02:00
|
|
|
|
* `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
|
|
|
|
|
|
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
|
|
|
|
|
|
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 22:59:14 +02:00
|
|
|
|
|
2016-10-21 21:15:35 +02:00
|
|
|
|
* `danger`
|
2017-01-05 08:31:58 +01:00
|
|
|
|
* `error`
|
2016-09-02 22:59:14 +02:00
|
|
|
|
|
2017-01-05 08:31:58 +01:00
|
|
|
|
### Bug
|
2016-09-02 22:59:14 +02:00
|
|
|
|
|
2016-10-21 21:15:35 +02:00
|
|
|
|
Example:
|
2016-09-23 11:56:25 +02:00
|
|
|
|
|
2016-10-21 21:15:35 +02:00
|
|
|
|
``` markdown
|
2017-01-05 08:31:58 +01:00
|
|
|
|
!!! bug
|
2016-10-21 21:15:35 +02: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 22:59:14 +02:00
|
|
|
|
|
2016-10-21 21:15:35 +02:00
|
|
|
|
Result:
|
2016-09-02 22:59:14 +02:00
|
|
|
|
|
2017-01-05 08:31:58 +01:00
|
|
|
|
!!! bug
|
2016-10-21 21:15:35 +02: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 22:59:14 +02:00
|
|
|
|
|
2016-10-21 21:15:35 +02:00
|
|
|
|
Qualifiers:
|
2016-09-02 22:59:14 +02:00
|
|
|
|
|
2016-10-21 21:15:35 +02:00
|
|
|
|
* `bug`
|
