A preprocessor for mdbook to add Material Design admonishments, based on the mkdocs-material implementation.
It turns this:
```admonish info
A beautifully styled message.
```
into this:
Read the usage and reference here, to see the actual examples in action. You can see the source in the ./book subdirectory.
Other projects using mdbook-admonish:
Use any fenced code-block as you normally would, but annotate it with admonish <admonition type>:
```admonish example
My example is the best!
```
See the reference page for a list of supported admonitions. You'll find:
infowarningdangerexampleand 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.
```
A custom title can be provided, contained in a double quoted JSON string.
Note that JSON escapes must be escaped again - for instance, write \" as \\".
```admonish warning "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 ""
This will take a while, go and grab a drink of water.
```
Markdown and HTML can be used in the inner content, as you'd expect:
```admonish tip "_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:
~~~admonish bug
This syntax won't work in Python 3:
```python
print "Hello, world!"
```
~~~
If you want to provide custom styling to a specific admonition, you can attach one or more custom classnames:
```admonish note.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
```
Install the tool:
bash
cargo install mdbook-admonish
Then let mdbook-admonish add the required files and configuration:
```bash mdbook-admonish install path/to/your/book
mdbook-admonish install --css-dir ./assets/css . ```
This will add the following configuration to your book.toml:
```toml [preprocessor.admonish] command = "mdbook-admonish"
[output.html] additional-css = ["./mdbook-admonish.css"] ```
and copy the file mdbook-admonish.css into your book's directory.
Then, build your book as usual:
bash
mdbook path/to/book
Please note, when updating your version of mdbook-admonish, updated styles will not be applied unless you rerun mdbook-admonish install to update the additional CSS files in your book.
Project design
compile_assets folder for details.mdbook-admonish install is responsible for delivering additional assets and configuration to a client book.mdbook-admonish is responsible for preprocessing book data, adding HTML that references compiled classnames.This utility is heavily drawn from and inspired by other projects, namely:
The licences for these projects are included in the licences folder.