Debian Codegraph @

docs/extensions/admonition.md

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