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
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
|
# mdbook-admonish
<!-- toc -->
## Intoduction
[](https://crates.io/crates/mdbook-admonish)
[](https://docs.rs/mdbook-admonish)
A preprocessor for [mdbook](https://github.com/rust-lang/mdBook) to add [Material Design](https://material.io/design) admonishments, based on the [mkdocs-material](https://squidfunk.github.io/mkdocs-material/reference/admonitions/) implementation.
It turns this:
````
```admonish info
A beautifully styled message.
```
````
into this:
```admonish info
A beautifully styled message.
```
## Usage
### A basic `admonish` block
Use any [fenced code-block](https://spec.commonmark.org/0.30/#fenced-code-blocks) as you normally would, but annotate it with `admonish <admonition type>`:
````
```admonish example
My example is the best!
```
````
```admonish example
My example is the best!
```
See the [list of directives](./reference.md#directives) for a full list of supported admonitions. You'll find:
- `info`
- `warning`
- `danger`
- `example`
and quite a few more!
You can also leave out the admonition type altogether, in which case it will default to `note`:
````
```admonish
A plain note.
```
````
```admonish
A plain note.
```
### Invalid blocks
By default, if an `admonish` block cannot be parsed, an error will be rendered in the output:
````
```admonish title="\j"
This block will error
```
````
```admonish title="\j"
This block will error
```
You can also configure the build to fail loudly, by setting `on_failure = "bail"` in `book.toml`. See the [configuration reference](./reference.md#booktoml-configuration) for more details.
### Additional Options
You can pass additional options to each block. The options are structured as TOML key-value pairs.
Note that some options can be passed globally, through the `default` section in `book.toml`. See the [configuration reference](./reference.md#booktoml-configuration) for more details.
#### Custom title
A custom title can be provided, contained in a double quoted TOML string.
Note that TOML escapes must be escaped again - for instance, write `\"` as `\\"`.
````
```admonish warning title="Data loss"
The following steps can lead to irrecoverable data corruption.
```
````
```admonish warning title="Data loss"
The following steps can lead to irrecoverable data corruption.
```
You can also remove the title bar entirely, by specifying the empty string:
````
```admonish success title=""
This will take a while, go and grab a drink of water.
```
````
```admonish success title=""
This will take a while, go and grab a drink of water.
```
#### Nested Markdown/HTML
Markdown and HTML can be used in the inner content, as you'd expect:
````
```admonish tip title="_Referencing_ and <i>dereferencing</i>"
The opposite of *referencing* by using `&` is *dereferencing*, which is
accomplished with the <span style="color: hotpink">dereference operator</span>, `*`.
```
````
```admonish tip title="_Referencing_ and <i>dereferencing</i>"
The opposite of *referencing* by using `&` is *dereferencing*, which is
accomplished with the <span style="color: hotpink">dereference operator</span>, `*`.
```
If you have code blocks you want to include in the content, use [tildes for the outer code fence](https://spec.commonmark.org/0.30/#fenced-code-blocks):
````
~~~admonish bug
This syntax won't work in Python 3:
```python
print "Hello, world!"
```
~~~
````
```admonish bug
This syntax won't work in Python 3:
~~~python
print "Hello, world!"
~~~
```
#### Custom styling
If you want to provide custom styling to a specific admonition, you can attach one or more custom classnames:
````
```admonish note class="custom-0 custom-1"
Styled with my custom CSS class.
```
````
Will yield something like the following HTML, which you can then apply styles to:
```html
<div class="admonition note custom-0 custom-1"
...
</div>
```
#### Custom CSS ID
If you want to customize the CSS `id` field, set `id="custom-id"`.
This will ignore [`default.css_id_prefix`](reference.md#default).
The default id is a normalized version of the admonishment's title,
prefixed with the `default.css_id_prefix`,
with an appended number if multiple blocks would have the same id.
Setting the `id` field will *ignore* all other ids and the duplicate counter.
````
```admonish info title="My Info" id="my-special-info"
Link to this block with `#my-special-info` instead of the default `#admonition-my-info`.
```
````
#### Collapsible
For a block to be initially collapsible, and then be openable, set `collapsible=true`:
````
```admonish collapsible=true
Content will be hidden initially.
```
````
Will yield something like the following HTML, which you can then apply styles to:
```admonish collapsible=true
Content will be hidden initially.
```
|
