458 lines
11 KiB
Markdown
458 lines
11 KiB
Markdown
# Admonition
|
||
|
||
[Admonition][1] is an extension included in the standard Markdown library that
|
||
makes it possible to add block-styled side content to your documentation, for
|
||
example summaries, notes, hints or warnings.
|
||
|
||
[1]: https://python-markdown.github.io/extensions/admonition/
|
||
|
||
## 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][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.
|
||
```
|
||
|
||
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.
|
||
|
||
[2]: #types
|
||
|
||
### Changing the title
|
||
|
||
By default, the block title will equal the type qualifier in titlecase. However,
|
||
it can easily 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"
|
||
|
||
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 setting a [custom 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:
|
||
|
||
!!! 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.
|
||
|
||
[3]: #changing-the-title
|
||
|
||
### 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.
|
||
|
||
However, 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:
|
||
|
||
!!! 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.
|
||
|
||
``` 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';
|
||
```
|
||
|
||
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
|
||
of the inserted block. Following is a list of type qualifiers provided by the
|
||
Material theme, 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
|
||
|
||
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`
|
||
|
||
### Abstract
|
||
|
||
Example:
|
||
|
||
``` markdown
|
||
!!! 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:
|
||
|
||
!!! 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.
|
||
|
||
Qualifiers:
|
||
|
||
* `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
|
||
|
||
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
|
||
|
||
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
|
||
|
||
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
|
||
|
||
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:
|
||
|
||
* `danger`
|
||
* `error`
|
||
|
||
### Bug
|
||
|
||
Example:
|
||
|
||
``` 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.
|
||
```
|
||
|
||
Result:
|
||
|
||
!!! 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.
|
||
|
||
Qualifiers:
|
||
|
||
* `bug`
|
||
|
||
### 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`
|
||
|
||
### 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`
|