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:
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:
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 reference page for a list of supported admonitions. You'll find:
infowarningdangerexampleand 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.
```
See the mdbook-admonish book for additional options, such as:
Install the tool:
bash
cargo install mdbook-admonish
Then let mdbook-admonish add the required files and configuration:
```bash
mdbook-admonish install path/to/your/book
mdbook-admonish install --css-dir ./assets/css . ```
This will add the following configuration to your book.toml:
```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:
bash
mdbook path/to/book
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:
log
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:
bash
cargo install mdbook-admonish --vers "1.5.0" --locked
You can ensure that content inlined with {{#include}} is also processed by setting the after option:
toml
[preprocessor.admonish]
after = ["links"]
This will expand include directives, before expanding admonish blocks.
Guarantees provided are as follows:
mdbook-admonish install to be rerun.
mdbook-admonish install to reinstall assets may break your build.mdbook preprocessor architecture. Relevant issues that may alleviate this:Project design
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/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.To make a breaking change in CSS, you should:
./src/bin/assets/VERSION./src/REQUIRED_ASSETS_VERSIONYou must make the next mdbook-admonish crate version at least a minor version bump.
Github workflows are setup such that pushing a vX.Y.Z tag will trigger a release to be cut.
This utility is heavily drawn from and inspired by other projects, namely:
The licences for these projects are included in the licences folder.