Alerts

Alerts

~~~admonish info
A beautifully styled message.
~~~

into this:

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

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

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

'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`, `\`, `"`

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

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

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

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

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>

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:

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 title='expensive'
Remember, this operation costs money!
~~~