mdbook-admonish 1.10.0

A preprocessor for mdbook to add Material Design admonishments.
Documentation

mdbook-admonish

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:

Simple Message

Examples

Read the documentation here, to see the actual examples in action. You can see the source in the ./book subdirectory.

Other projects using mdbook-admonish:

Usage

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

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

Best Example

See the reference page for a 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.
```

Plain Note

Additional Options

See the mdbook-admonish book for additional options, such as:

  • Custom titles
  • Custom styling
  • Collapsible blocks

Installation

Install the tool:

cargo install mdbook-admonish

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

# Note: this may need to be rerun for new minor versions of mdbook-admonish
# see the 'Semantic Versioning' section below for details.
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.

mdbook will fail the build if you require newer assets than you have installed:

2022-04-26 12:27:52 [INFO] (mdbook::book): Book building has started
ERROR:
  Incompatible assets installed: required mdbook-admonish assets version '^2.0.0', but found '1.0.0'.
  Please run `mdbook-admonish install` to update installed assets.
2022-04-26 12:27:52 [ERROR] (mdbook::utils): Error: The "admonish" preprocessor exited unsuccessfully with exit status: 1 status

If you want to update across minor versions without breakage, you should always run mdbook-admonish install.

Alternatively, pin to a specific version for a reproducible installation:

cargo install mdbook-admonish --vers "1.5.0" --locked

Process included files

You can ensure that content inlined with {{#include}} is also processed by setting the after option:

[preprocessor.admonish]
after = ["links"]

This will expand include directives, before expanding admonish blocks.

Semantic Versioning

Guarantees provided are as follows:

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.

Scripts to get started

  • ./scripts/install installs other toolchains required for development
  • ./scripts/check runs a full CI check
  • ./scripts/rebuild-book rebuilds the reference book under ./book. This is useful for integration testing locally.

Making breaking changes in CSS

To make a breaking change in CSS, you should:

  • Update the assets version in ./src/bin/assets/VERSION
  • Update the required assets version specifier in ./src/REQUIRED_ASSETS_VERSION

You must make the next mdbook-admonish crate version at least a minor version bump.

Releasing

Github workflows are setup such that pushing a vX.Y.Z tag will trigger a release to be cut.

Once the release is created, copy and paste the relevant section of CHANGELOG.md manually to update the description.

Thanks

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

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