mirror of
https://github.com/squidfunk/mkdocs-material.git
synced 2024-11-28 09:20:52 +01:00
316 lines
7.9 KiB
Markdown
316 lines
7.9 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, hints, notes or warnings.
|
||
|
||
[1]: https://pythonhosted.org/Markdown/extensions/admonition.html
|
||
|
||
## 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
|
||
!!! hint
|
||
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:
|
||
|
||
!!! hint
|
||
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.
|
||
|
||
### Changing the title
|
||
|
||
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
|
||
!!! hint "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:
|
||
|
||
!!! hint "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](#changing-the-title), the icon and title
|
||
can be omitted by providing an empty string after the type qualifier:
|
||
|
||
Example:
|
||
|
||
``` markdown
|
||
!!! hint ""
|
||
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:
|
||
|
||
!!! hint ""
|
||
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.
|
||
|
||
However, the [PyMdown Extensions][2] package adds an extension called
|
||
[SuperFences][3], which makes it possible to nest code blocks within other
|
||
blocks.
|
||
|
||
[2]: https://facelessuser.github.io/pymdown-extensions
|
||
[3]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/
|
||
|
||
Example:
|
||
|
||
!!! hint
|
||
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.
|
||
|
||
## 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
|
||
qualifiers, is [hint](#hint).
|
||
|
||
### Hint
|
||
|
||
Example:
|
||
|
||
``` markdown
|
||
!!! hint
|
||
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:
|
||
|
||
!!! hint
|
||
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:
|
||
|
||
* `hint`
|
||
* `note`
|
||
|
||
### 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`
|
||
* `idea`
|
||
|
||
### 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`
|
||
* `attention`
|
||
* `important`
|
||
|
||
### 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`
|
||
* `caution`
|
||
|
||
### Error
|
||
|
||
Example:
|
||
|
||
``` markdown
|
||
!!! error
|
||
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:
|
||
|
||
!!! error
|
||
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:
|
||
|
||
* `error`
|
||
* `bug`
|