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`
|