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 usage and reference 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.
```
A custom title can be provided, contained in a double quoted JSON string.
Note that JSON escapes must be escaped again - for instance, write \" as \\".
```admonish warning "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 ""
This will take a while, go and grab a drink of water.
```
Markdown and HTML can be used in the inner content, as you'd expect:
```admonish tip "_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!"
```
~~~
If you want to provide custom styling to a specific admonition, you can attach one or more custom classnames:
```admonish note.custom-0.custom-1
Styled with my custom CSS class.
```
Will yield something like the following HTML, which you can then apply styles to:
```html
```
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
Guarantees provided are as follows:
mdbook-admonish install to be rerun.
mdbook-admonish install to reinstall assets may break your build.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.
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 licences folder.