mdbook-admonish

Intoduction

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.

Reference

`book.toml` configuration

See below for all configuration options available to add in book.toml.

The options should all be nested under preprocessor.admonish; for example:

[preprocessor.admonish]
on_failure = "bail"

[preprocessor.admonish.default]
collapsible = true

[preprocessor.admonish.renderer.test]
render_mode = "strip"

`on_failure`

Optional. Default value: continue.

The action to take when an invalid admonish block is encountered:

continue (default): Continue processing future blocks, do not fail the build. If rendering to HTML, an error message will be displayed in the book output.
bail: Abort the build.

`default`

Optional.

Default values to use, when not provided in an admonish block explicitly.

Subfields:

default.title (optional): Title to use for blocks. Defaults to the directive used in titlecase.
default.collapsible (optional, default: false): Make blocks collapsible by default when set to true.
default.css_id_prefix (optional, default: "admonition-"): The default css id prefix to add to the id of all blocks. Ignored on blocks with an id field.

`renderer`

Tip

It is recommended that you set:

[preprocessor.admonish.renderer.test]
render_mode = "strip"

This allows mdbook test to find and test rust examples within admonish blocks.

This will be the default behaviour in the next mdbook-admonish major version.

Optional.

Additional settings to apply, depending on the renderer that is running.

The most common renderers used are:

html: Used by mdbook build to build the final book output.
test: Used by mdbook test to find and run doctests.

Subfields:

renderer.<renderer_name>.render_mode (optional): The action mdbook-admonish should take when running with this renderer.
- Valid values:
  - html: Convert admonish blocks into HTML output.
  - preserve: Do nothing. Leave the book untouched.
  - strip: Strip admonish-specific syntax, leaving the inner content untouched.
- Default values:
  - For the html renderer, the default value is html.
  - For all other renderers, the default value is preserve.

`directive`

Optional.

Settings relating to each type of block.

`builtin`

Optional.

Override the settings of a builtin directive.

The subkey of builtin is the directive to override. This must be the first directive listed in the Directives section below, e.g. warning (not caution or other aliases).

[preprocessor.admonish.directive.builtin.warning]
collapsible = true

Subfields:

collapsible (optional): The default boolean value of the collapsible property for this type of block.

`custom`

Optional.

Additional types of block to support. The subkey of custom is the new directive to support.

You must run mdbook-admonish generate-custom after updating these values, to generate the correct styles.

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

Subfields:

icon: A filepath relative to the book root to load an SVG icon from.
color: An RGB hex encoded color to use for the icon.
collapsible (optional): The default boolean value of the collapsible property for this type of block.
aliases (optional): One or more alternative directives to use this block.
title (optional): The default title for this type of block. If not specified, defaults to the directive in title case. To give each alias a custom title, add multiple custom blocks.

`command`

Required.

Used by mdbook to know how to call the mdbook-admonish plugin.

Running this command with the --version flag from your shell should work, for the plugin to function.

`assets_version`

Optional.

This is automatically updated by mdbook-admonish install and should not be edited.

Directives

All supported directives are listed below.

Custom directives can be added via the custom config option above.

note

Note