It turns this:
```admonish info A beautifully styled message. ```
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:
and quite a few more!
You can also leave out the admonition type altogether, in which case it will default to
```admonish A plain note. ```
mdbook-admonish book for additional options, such as:
- Custom titles
- Custom styling
- Collapsible blocks
Install the tool:
cargo install mdbook-admonish
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
[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:
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
Alternatively, pin to a specific version for a reproducible installation:
cargo install mdbook-admonish --vers "1.5.0" --locked
Bail on error
By default, if an adomnition is incorrectly configured, an error will be shown in the book.
You can force it to break the build instead, with the following configuration:
[preprocessor.admonish] on_failure = "bail"
This may be useful for non-interative workflows.
Guarantees provided are as follows:
- Major versions: Contain breaking changes to the user facing markdown API, or the public API of the crate itself.
- Minor versions: Feature release. May contain changes to generated CSS/HTML requiring
mdbook-admonish installto be rerun.
- Patch versions: Bug fixes only.
- Compiled CSS styles are built and committed from SCSS sources. See the
compile_assetsfolder for details.
mdbook-admonish installis responsible for delivering additional assets and configuration to a client book.
mdbook-admonishis responsible for preprocessing book data, adding HTML that references compiled classnames.
Scripts to get started
./scripts/installinstalls other toolchains required for development
./scripts/checkruns a full CI check
./scripts/rebuild-bookrebuilds 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
- Update the required assets version specifier in
You 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.
Once the release is created, copy and paste the relevant section of
CHANGELOG.md manually to update the description.
This utility is heavily drawn from and inspired by other projects, namely:
The licences for these projects are included in the