mdbook-admonish

Intoduction

Latest version docs.rs

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:

Info

A beautifully styled message.

Usage

A basic admonish block

Use any fenced code-block as you normally would, but annotate it with admonish <admonition type>:

```admonish example
My example is the best!
```

Example

My example is the best!

See the list of 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.
```

Note

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
```

Error rendering admonishment

Failed with:

'title="\j"' is not a valid directive or TOML key-value pair.

TOML parsing error: TOML parse error at line 1, column 21
  |
1 | config = { title="\j" }
  |                     ^
invalid escape sequence
expected `b`, `f`, `n`, `r`, `t`, `u`, `U`, `\`, `"`

Original markdown input:

```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 for more details.

Additional Options

You can pass additional options to each block. Options are given like a TOML Inline Table, as key-value pairs separated by commas.

mdbook-admonish parses options by wrapping your options in an inline table before parsing them, so please consult The TOML Reference if you run into any syntax errors. Be aware that:

  • Key-value pairs must be separated with a comma ,
  • TOML escapes must be escaped again - for instance, write \" as \\".
  • For complex strings such as HTML, you may want to use a literal string to avoid complex escape sequences

Note that some options can be passed globally, through the default section in book.toml. See the configuration reference for more details.

Custom title

A custom title can be provided:

```admonish warning title="Data loss"
The following steps can lead to irrecoverable data corruption.
```

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.
```

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>, `*`.
```

Referencing and dereferencing

The opposite of referencing by using & is dereferencing, which is accomplished with the dereference operator, *.

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

Bug

This syntax won't work in Python 3:

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 title="Stylish", 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:

<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.

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 title="Sneaky", collapsible=true
Content will be hidden initially.
```

Will yield something like the following HTML, which you can then apply styles to:

Sneaky

Content will be hidden initially.

Custom blocks

You can add new block types via the book.toml config:

# book.toml

[[preprocessor.admonish.custom]]
directive = "expensive"
icon = "./money-bag.svg"
color = "#24ab38"
aliases = ["money", "cash", "budget"]

You must then generate the relevant CSS file, and reference it in the output.html section. mdbook-admonish has a helper to quickly do this for you:

# Generates a file at ./mdbook-admonish-custom.css with your styles in
$ mdbook-admonish generate-custom ./mdbook-admonish-custom.css
# book.toml

[output.html]
# Reference the new file, so it's bundled in with book styles
additional-css = ["./mdbook-admonish.css", "./mdbook-admonish-custom.css"]

You can then reference the new directive (or alias) like usual in your blocks.

```admonish expensive
Remember, this operation costs money!
```

Expensive

Remember, this operation costs money!

You can also set a default title. See the Reference page for more details.