1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
|
title: Admonition Extension
Admonition
==========
Summary
-------
The Admonition extension adds [rST-style][rST] admonitions to Markdown documents.
This extension is included in the standard Markdown library.
[rST]: http://docutils.sourceforge.net/docs/ref/rst/directives.html#specific-admonitions
Syntax
------
Admonitions are created using the following syntax:
```md
!!! type "optional explicit title within double quotes"
Any number of other indented markdown elements.
This is the second paragraph.
```
`type` will be used as the CSS class name and as default title. It must be a
single word. So, for instance:
```md
!!! note
You should note that the title will be automatically capitalized.
```
will render:
```html
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>You should note that the title will be automatically capitalized.</p>
</div>
```
Optionally, you can use custom titles. For instance:
```md
!!! danger "Don't try this at home"
...
```
will render:
```html
<div class="admonition danger">
<p class="admonition-title">Don't try this at home</p>
<p>...</p>
</div>
```
If you don't want a title, use a blank string `""`:
```md
!!! important ""
This is an admonition box without a title.
```
results in:
```html
<div class="admonition important">
<p>This is an admonition box without a title.</p>
</div>
```
You can also provide additional CSS class names separated by spaces. The first
class should be the "type." For example:
```md
!!! danger highlight blink "Don't try this at home"
...
```
will render:
```html
<div class="admonition danger highlight blink">
<p class="admonition-title">Don't try this at home</p>
<p>...</p>
</div>
```
rST suggests the following "types": `attention`, `caution`, `danger`, `error`,
`hint`, `important`, `note`, `tip`, and `warning`; however, you're free to use
whatever you want.
Styling
-------
There is no CSS included as part of this extension. Check out the default
[Sphinx][sphinx] theme for inspiration.
[sphinx]: https://www.sphinx-doc.org/en/master/
## Usage
See [Extensions](index.md) for general extension usage. Use `admonition` as the
name of the extension.
This extension does not accept any special configuration options.
A trivial example:
```python
markdown.markdown(some_text, extensions=['admonition'])
```
|
