tommilligan/mdbook-admonish

A preprocessor for mdbook to add Material Design admonishments.

mdbook-admonish

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:

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:

• The Rhai Book

Usage

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:

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

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

# If you get compilation/installation errors, try a locked installation
cargo install mdbook-admonish --locked

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

Reproducible builds

For a reproducible build suitable for use in CI or scripts, please:

• Pin to a specific version
• Install with lockfile dependencies
• Always install the latest CSS assets

cargo install mdbook-admonish --vers "1.5.0" --locked
mdbook-admonish install path/to/your/book

The Minimum Supported Rust Version (MSRV) is documented in Cargo.toml, and noted in the CHANGELOG.md. We aims to support around six months of stable Rust.

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.

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:

• 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 install to be rerun.
  • Note: updating acrosss minor versions without running mdbook-admonish install to reinstall assets may break your build.
  • This is due to limitations in the mdbook preprocessor architecture. Relevant issues that may alleviate this:
    • rust-lang/mdBook#1222
    • rust-lang/mdBook#1687
    • rust-lang/mdBook#1689
• Patch versions: Bug fixes only.

Development

See CONTRIBUTING.md for guidelines on developing.

Thanks

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

• mdbook-mermaid
• mkdocs-material
• material-design-icons

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

mdbook-admonish's Issues

After updating to `v1.12.0`, I get a panic as `byte index XX is not a char boundary;`

Hello, thanks for the last time! 😆

I had a little trouble this time, after updating mdbook-admonish to v1.12.0, when I did the mdbook build, the process was interrupted by a panic.... 😢

📁 Markdown file (click me)

# Chapter 1

例えばこれは`ng` です😅
`Abc`and`Def`ghi

```admonish success title=""
![example](example.webp)

<div style="text-align: right;font-style: italic;" >
    Screenshot of abcdefg hi jklMN opqrstu Vwxyzab cde etc...
</div>
```

A preprocessor for mdbook to add Material Design admonishments, based on the mkdocs-material implementation.
ac
It turns this:

```admonish info
A beautifully styled message.
```

into this:

Simple Message

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:

    The Rhai Book

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

> RUST_BACKTRACE=full mdbook build
2023-09-19 12:28:20 [INFO] (mdbook::book): Book building has started
thread 'main' panicked at 'byte index 14 is not a char boundary; it is inside '例' (bytes 13..16) of `# Chapter 1

例えばこれは`ng` です😅
`Abc`and`Def`ghi

```admonish success title=""
![example](example.webp)

<div style="text-align: right;font-style: italic;" >
    Screenshot of abcdefg hi jklMN opqrstu Vwxyzab cde etc...
</div>
```

A preproc`[...]', /Users/xxx/.cargo/registry/src/index.crates.io-6f17d22bba15001f/mdbook-admonish-1.12.0/src/markdown.rs:38:26
stack backtrace:
   0:        0x104e2c5b0 - __mh_execute_header
   1:        0x104e47230 - __mh_execute_header
   2:        0x104e2a184 - __mh_execute_header
   3:        0x104e2c408 - __mh_execute_header
   4:        0x104e2d82c - __mh_execute_header
   5:        0x104e2d5bc - __mh_execute_header
   6:        0x104e2dd5c - __mh_execute_header
   7:        0x104e2dc68 - __mh_execute_header
   8:        0x104e2c990 - __mh_execute_header
   9:        0x104e2d9d4 - __mh_execute_header
  10:        0x104e5cbfc - __mh_execute_header
  11:        0x104e4acc4 - __mh_execute_header
  12:        0x104e5d0b8 - __mh_execute_header
  13:        0x104ccd0bc - __mh_execute_header
  14:        0x104cd1854 - __mh_execute_header
  15:        0x104cca974 - __mh_execute_header
  16:        0x104c96c60 - __mh_execute_header
  17:        0x104c9c414 - __mh_execute_header
  18:        0x104ca4654 - __mh_execute_header
  19:        0x104e2552c - __mh_execute_header
  20:        0x104c987d8 - __mh_execute_header
2023-09-19 12:28:20 [ERROR] (mdbook::utils): Error: The "admonish" preprocessor exited unsuccessfully with exit status: 101 status

I thought it was simply a bad multibyte character, so I tried the following...?

📁 Markdown

# Chapter 1

例えばこれは`ng` です😅
`Abc`and`Def`ghi

This seems to be OK.

At this point, I have no idea anymore, but what confuses me even more is that if I delete a few lines from the first file, it somehow becomes OK.

📁 Markdown

# Chapter 1

例えばこれは`ok` です😄
`Abc`and`Def`ghi

```admonish success title=""
![example](example.webp)

<div style="text-align: right;font-style: italic;" >
    Screenshot of abcdefg hi jklMN opqrstu Vwxyzab cde etc...
</div>
```

A preprocessor for mdbook to add Material Design admonishments, based on the mkdocs-material implementation.
It turns this:

```admonish info
A beautifully styled message.
```

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:

    The Rhai Book

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

(...I can't help but wonder why this is OK.)

All I know is that if the error occurs, the problem definitely occurs at markdown.rs:38:26.

Sorry for the vague report.
I hope it helps... 😓

Add a hosted demo book

Host a demo book statically somewhere, with source code available. Probably a different repo, that then gets rendered to GH pages automatically on push?

admonish code block do not render properly

I use mdbook-admonish in my book. To test the installation, I wrote:

Some text

'''admonish
A beautifully styled message.
'''

(replace the ' with markdown's fenced block syntax)

When building the book with mdbook serve --open, the block is rendered as plain text without any style and without errors or warnings. I downloaded the package today and I updated mdbook to v0.4.25.

The installation process didn't yield any error either. I installed the package with cargo install mdbook-admonish & mdbook-admonish install path/to/my_book with path/to/my_book set to the correct path.

Attached to this issue, is a minimal working example (as a .zip archive) with all the plugins I use in the book.

docs.zip

mdbook without installation possible?

Hello Tom Milligan @tommilligan,

thank you very much for your great work.

Is there any way to use the exe file without mdbook-admonish install?
I can`t / am not allowed to install anything on my computer.

Thanks for your time and sorry for asking my question here, I didn`t find any forum or similar unfortunately.

Many greetings
rufus42

While converting the book to pdf, the admonish blocks are not rendered properly.

Hi @tommilligan,

Good morning.
I tried to use the admonish block for creating the mdbook and tried to convert the book to pdf using below two options:

• Using Ctrl+P in chrome
• Using mdbook-pdf tool

But both the method yielded in not getting the proper formatted block.

Could you please help @tommilligan

PDF output

Problem during installing mdbook-admonish

Good morning, I was installing mdbook-admonish but the following problem appeared:

Cannot compile

Hi! Unfortunately I can't get 0.10.0 and 0.10.1 to compile. The same error shows up on both Windows as well as macOS with the latest Rust version (1.71.1).

   Compiling mdbook v0.4.33
   Compiling mdbook-admonish v1.10.1
error[E0308]: mismatched types
  --> /Users/sander/.cargo/registry/src/index.crates.io-6f17d22bba15001f/mdbook-admonish-1.10.1/src/book_config.rs:9:30
   |
9  |       let table: toml::Table = ctx
   |  ________________-----------___^
   | |                |
   | |                expected due to this
10 | |         .config
11 | |         .get_preprocessor("admonish")
12 | |         .context("No configuration for mdbook-admonish in book.toml")?
13 | |         .to_owned();
   | |___________________^ expected `Map<String, Value>`, found a different `Map<String, Value>`
   |
   = note: `Map<String, Value>` and `Map<String, Value>` have similar names, but are actually distinct types
note: `Map<String, Value>` is defined in crate `toml`
  --> /Users/sander/.cargo/registry/src/index.crates.io-6f17d22bba15001f/toml-0.5.11/src/map.rs:32:1
   |
32 | pub struct Map<K, V> {
   | ^^^^^^^^^^^^^^^^^^^^
note: `Map<String, Value>` is defined in crate `toml`
  --> /Users/sander/.cargo/registry/src/index.crates.io-6f17d22bba15001f/toml-0.7.6/src/map.rs:32:1
   |
32 | pub struct Map<K, V> {
   | ^^^^^^^^^^^^^^^^^^^^
   = note: perhaps two different versions of crate `toml` are being used?

For more information about this error, try `rustc --explain E0308`.
error: could not compile `mdbook-admonish` (lib) due to previous error
error: failed to compile `mdbook-admonish v1.10.1`, intermediate artifacts can be found at `/var/folders/1t/pcxhs0r11zjb8_l47w6wrzwh0000gn/T/cargo-install9dd3kl`

`cargo install --locked mdbook-admonish` fails

I'm not sure how it could fail given that it used to succeed — I thought the role of --locked was to prevent this. But it generates this for me on a 1.64 compiler:

error[E0597]: `local_ctx` does not live long enough
   --> /Users/maximilian/.cargo/registry/src/github.com-1ecc6299db9ec823/mdbook-0.4.18/src/renderer/html_handlebars/helpers/navigation.rs:154:25
    |
154 |             t.render(r, &local_ctx, &mut local_rc, out)
    |                         ^^^^^^^^^^ borrowed value does not live long enough
155 |         })?;
    |         -
    |         |
    |         `local_ctx` dropped here while still borrowed
    |         borrow might be used here, when `local_rc` is dropped and runs the destructor for type `handlebars::RenderContext<'_, '_>`
    |
    = note: values in a scope are dropped in the opposite order they are defined

For more information about this error, try `rustc --explain E0597`.
error: could not compile `mdbook` due to previous error
warning: build failed, waiting for other jobs to finish...
    Building [=======================> ] 240/243: toml_edit
error: failed to compile `mdbook-admonish v1.7.0`, intermediate artifacts can be found at `/var/folders/q2/jxfwc8mn3gvf0cs0mqk83thm0000gn/T/cargo-installm1zcJW`

(There's a warning about using a yanked dependency, but again, I thought it could still use it)

Running cargo install --path . --locked on main works — would it be possible if we could release a new version? And FYI the original command works without --locked.

Set collapsible default value per directive

Hi!

If I'm not mistaken, currently it seems that the default collapsible value must be set globally for all directives.

It would be great if it were possible to set this default value to true for specific directives only.

Admonish doesn't work with `mdbook test`

If I use an admonish example (or other box) containing a code example, mdbook test will not test that example.
Here's an example of an example that doesn't get tested.

``````admonish example
Here's an example
```rust
let x = 10;
x = 20;
```
``````

If I take it out of an admonish example fenced code block, the code is tested (and fails as expected).

Is there a way to make this work?

Add ID from title

It would be good to have, say, the following:

```admonish tip "Hello"
...
```

to generate a div with an id (like for MarkDown titles) that comes from the title:

<div class="admonition-title" id="hello">

This way it is possible to refer to this admonition in a URL link.

[feature]: admonish discriminator

I have encountered two issues with the current methods of indicating adomonish blocks:

1. Prettier breaks "super-blocks"

When wrapping codeblocks in an admonish block, prettier changes the current discriminator (~~~) to the more common quadruple backtick (````):

Before Prettier

~~~admonish
```json
{}
```
~~~

After Prettier

````admonish
```json
{}
```
````

2. I miss the syntax highlighting within admonish blocks

---

Suggestions

a) Use an alternate, completely unique, discriminator:

Alternatives

:::admonish
```json
{}
```
:::

!!!admonish
```json
{}
```
!!!

b) Accept quadruple backticks:

mdbook-admonish/src/lib.rs

Line 223 in e8813eb

const POST: &str = "```";

bonus points if it is made possible to wrap an admonish block within an admonish block

sorry for all the noise from my end

TLDR admonish rendering

Right now the tldr admonishment renders as Tldr. It would be nice if this would render as TL;DR instead.

[VISUAL BUG] - Header Bar Overflow

Hi 👋, just wanted to say that I really like this library and thank you for making it!

Issue

However, I have noticed one thing though with the Header Bar in the given code blocks, they seem to overflow and not line up.

Example

	```admonish <admonition type>
	[insert text]
	```

Results in:

It's like one or two pixels off so not entirely noticeable but definitely visible. I was wondering if this was an issue with the library or something potentially on the client-side? I've not changed any CSS within the generated CSS file.

Diagnostic Info

Operating System: Windows 11
Rust: v1.58.1
mdbook: v0.4.18
mdbook-admonish: 1.5.0

setting to default to empty title

Personally, I find myself adding title="" to almost every admonishment.

It would be nice to have a flag to default to no title:

[preprocessor.admonish]
default-empty-title = true

---

That being said, I would also like to keep the icons in the ::before. I have tried spaces for titles, but get inconsistent styling for the colour -bar/strip:

I have found setting title = "​" alleviates the styling issues.

---

Is this something mdbook-admonish would be interested in?

Add collapsible admonition blocks

The mkdocs-material implementation allows for collapsible blocks, a pretty cool feature that allows for example to hide the answer to a question, which is invaluable for teaching material.

Would it be possible to add it to mdbook-admonish?

Admonishments inside lists restarts numbering

I have the following Markdown:

1. Thing one

   ```sh
   $ echo "Thing one"
   ```

1. Thing two

   ```sh
   $ echo "Thing two"
   ```

1. Thing three

   ```sh
   $echo $Thing three"
   ```

   ```admonish warning
   **Do not** run this
   ```

1. Thing 4

   ```sh
   $ echo "Thing four"
   ```

This doesn't quite get rendered correctly:

1. The admonishment isn't indented to align with the list item's text; instead it's aligned with the list numbers.
2. "Thing 4" gets rendered in its own <ol> resulting in the numbering starting from 1 again, instead of it continuing at 4.

I would like to see v1.9.0 released to crates.io as well.

Hello!

As the title says, any plans to release v1.9.0 on crates.io?
I am eagerly waiting for it!

I love mdbook-admonish because it makes the site look great 😆

Thanks!

Smart quotes doesn't work inside admonish blocks

1. Standard quotes are not turned into smart quotes inside the blocks even with the mdbook option turned on.

2. Also, it would be nice to be able to style the title text... in other words, specify the title text also as MarkDown...

3. Also, inlined HTML tags are not recognized:

4. Code blocks inside admonish blocks must be wrapped with ~~~ otherwise they conflict with the admonish closing tag

5. Also, symbols inside fenced code blocks inside admonish blocks are not recognized:

Adding new admonishes

Would be nice if new admonishes could be added by adding an icon and classes to the CSS.

I see that currently the directives are hardcoded.

I guess that would probably be a major change how this crate works.

Any way to specify inline?

Floating an block inline to the right or left is very useful and can be done via the inline style.

Can we add this?

Not working on including files?

Thank you for developing this easy-to-use extension.

In PRQL/prql#2366, I noticed that the admonish code block is not rendered as intended in the externally imported md file. (like below)
Perhaps this is a current limitation?

{{#include ../../../CHANGELOG.md}}

Code in admonish blocks?

Is it possible to have code blocks inside admonish blocks? Would be awesome for the "example" block type!

But I cannot think of a way that markup would look like... So maybe I'm just missing something...

translate title

hello,

is it possible to translate the titles?

additional-css UNIX style paths

UNIX style paths should always be used for additional-css.
When running mdbook-admonish on a UNIX system, the paths are (correctly) normalized:
Before:

additional-css = ['./path/to/mdbook-admonish.css']

After:

additional-css = ['./path/to/mdbook-admonish.css']

On a Windows system, mdbook-admonish causes the paths to be (inaccurately) normalized and duplicated:
Before:

additional-css = ['./path/to/mdbook-admonish.css']

After:

additional-css = ['./path/to/mdbook-admonish.css', '.\path\to\mdbook-admonish.css']

accessibility

Would admonish be interested in improving the accessibility of the generated HTML and CSS?

• details elements are missing indication they are clickable (e.g. details:hover { cursor: pointer; })
• Admonish blocks should contain sr-only titles for blocks without titles
• Block titles should be included in aria-labels, and/or use semantic elements (e.g. header maybe)

are there the tabs feature!

UPDATE

the best feature for me in mkdocs-material is the way that uses the tabs to groups codes

• is it supported by mdbook-admonish ?
• if not, is there any way to use this feature?

Error path when saving changed configuration to book.toml

When using:

mdbook-admonish install path/to/your/book

to install, the mdbook-admonish add wrong path:

path/to/your/book/./mdbook-admonish.css

to book.toml.

The way to install it isn't specified.

Hi, I found it hard to install it (This is my first mdbook), maybe there should be a section talking about that?

cargo install mdbook-admonish

Then

mdbook-admonish install

Isn't something that a new user would know. I needed to check the source code of this repo to figure it out

Admonition title bar too large in 1.6.0

Since the 1.6.0 update, admonition titles appear too large. I did update the CSS by running mdbook-admonition install again. Maybe this is related to the <a> fields that release added in the generation?

Feature Request: Provide prebuilt binaries for mdbook-admonish

Many other mdbook preprocessors provide prebuilt binaries. This helps to enable the use of preprocessors in automation scenarios.

For example I'm interested in using mdbook-admonish with the actions-mdbook github action. It currently requires prebuilt binaries, more details here: peaceiris/actions-mdbook#426 (comment)

Would you be willing to provide prebuilt binaries for mdbook-admonish?

It looks like you could probably just modify the existing actions workflow that mdboom-mermaid uses: https://github.com/badboy/mdbook-mermaid/blob/main/.github/workflows/deploy.yml

Compatibility with GitHub and Pandoc

Hi,

I've just started using mdBook and have added mdBook-admonish. The look is great.

I am slightly concerned for the future when it comes to publishing my book in formats other than HTML. It looks like the mdBook renderers for PDF and EPUB are a long way from finished. So I was wondering about using PanDoc for more mature pdf and epub support.

However, I think I will need to get PanDoc to interpret my mdBook files as if they are GitHub flavoured Markdown as it doesn't support mdBook at present. GitHub seems to have standardised on

> **Note**
> This is a note

> **Warning**
> This is a warning

although that seems contentious. I see that CommonMark is also having discussions about what format to use and I see that this is also suggested as a "better" solution:

:::note
This is a note
:::

:::warning
This is a warning
:::

While Microsoft are apparently using

> [!NOTE]
> Information the user should notice even if skimming.

> [!TIP]
> Optional information to help a user be more successful.

> [!IMPORTANT]
> Essential information required for user success.

> [!CAUTION]
> Negative potential consequences of an action.

> [!WARNING]
> Dangerous certain consequences of an action.

So the route of dBook-admonish of

```admonish quote
test quote
```

is unusual. Do you have any thoughts about supporting GitHub format or whatever Commonmark eventually decide on?

Handle empty title/content correctly

Currently, this breaks the CSS a bit.

Setting the title to empty string should explicitly remove the header bar.

Add property tests for content

Add property based tests to cover the following scenarios:

• Any valid code block should not cause a panic
• Any valid admonish block should not cause a panic
• Any generated block, should then be rendered in the way we expect by the downstream mdbook

Using mdbook-admonish changes the style of the `<details>` tag

After installing the package in the book, the style of the <summary> tag changed completely.

There are a number of :is calls in mdbook-admonish.css like :is(.admonition-title, summary) with the consequence that it changes the style of all summaries, not just those created by admonitions.

Can this be fixed?

Why does mdbook-admonish have such a strange install process?

Hey. I have some question about the whole mdbook-admonish install process.

I know no other mdBook addon (but I don't know a lot of addons) that would have such artificial versioning. It is nice to make sure that breaking changes aren't introduced, but it makes it pretty difficult to use mdbook-admonish "rolling release".

The most problems are caused by the mdbook-admonish.css file.

Why is the mdbook-admonish.css included within the released mdbook-admonish executable? Including large data files in executables is strange.

I use admonish on my website: https://meator.github.io/xbps-src-tutorials/. As I describe in its README, I have created a wrapper script whose purpose is to "undo" the efforts of admonish to be versioned. This script is pretty hacky.

admonish provides no way to output the raw mdbook-admonish.css file. This is why I'm asking why is the file hardcoded into the executable. If it were a freestanding file, I could just copy it in the script. But the only way I know of to convince the mdbook-admonish executable to let go of this file is to install it to a book. Because of this, I have to create a fake stub book in the script, install admonish to it and then use the generated mdbook-admonish.css file in the build process of the real book.

Am I expected to include the mdbook-admonish.css file in my git repository? Or should I instruct the user to run mdbook-admonish install before building my book? (I already have a script mentioned earlier that handles that, but I'm asking generally.) If it should be included in the repository, I am reluctant to include arbitrary data files which aren't directly related to the content of the website to the repository. This could be documented better either on the website or in this project's README.