mdbook-admonish

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:

Usage

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 mkdocs-material docs for a list of supported admonitions. You'll find:

• info
• warning
• danger
• example

and quite a few more!

Additional Options

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 leave out the admonition type altogether, in which case it will default to note:

```admonish
A plain note.
```

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!"
```
~~~

Installation

Install the tool:

cargo install mdbook-admonish

Then let mdbook-admonish add the required files and configuration:

mdbook-admonish install path/to/your/book

# optionally, specify a directory where CSS files live, relative to the book root
mdbook-admonish install --css-dir ./assets/css .

This will add the following configuration to your book.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:

mdbook path/to/book

Updates

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.

Development

Project design

• Compiled CSS styles are built and committed from SCSS sources. See the 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.

Thanks

This utility is heavily drawn from and inspired by other projects, namely:

• mdbook-mermaid
• mkdocs-material
• material-design-icons

The licences for these projects are included in the licences folder.