mdbook-admonish

• Intoduction
• Usage
  • A basic admonish block
  • Invalid blocks
  • Additional Options
    • Custom title
    • Nested Markdown/HTML
    • Custom styling
    • Custom CSS ID
    • Collapsible
  • Custom blocks

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:

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

TOML parsing error: TOML parse error at line 1, column 10
  |
1 | 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. The options are structured as TOML key-value pairs.

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, contained in a double quoted TOML string. Note that TOML escapes must be escaped again - for instance, write \" as \\".

```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 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 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 expensive
Remember, this operation costs money!
```

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

Reference

• book.toml configuration
  • on_failure
  • default
  • renderer
  • custom
  • command
  • assets_version
• Directives

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

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

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.

custom

Optional.

Additional type of block to support. You must run mdbook-admonish generate-custom after updating these values, to generate the correct styles.

Add blocks using TOML's Array of Tables notation:

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

Subfields:

• directive: The keyword to use this type of block.
• 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.
• 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

abstract, summary, tldr

info, todo

tip, hint, important

success, check, done

question, help, faq

warning, caution, attention

failure, fail, missing

danger, error

bug

example

quote, cite