A preprocessor for mdbook to add Material Design admonishments.

Last update: Jun 10, 2022

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

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.

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.
  • Patch versions: Bug fixes only.

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.

GitHub

https://github.com/tommilligan/mdbook-admonish
Comments
  • 1. 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?

    Reviewed by gggto at 2022-04-25 21:47
  • 2. 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:

    image

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

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

    image

    Reviewed by schungx at 2022-02-19 06:00
  • 3. Add collapsible support

    This Pull Request adds collapsible admonition support, as described in https://github.com/tommilligan/mdbook-admonish/issues/18.

    In its current state, this implementation has 2 shortcomings that I'm not sure how to overcome:

    1. The CSS could be modified to make the arrow look slightly better.
    2. The links to the admonition titles interfere with the open/close interaction. Clicking on the title doesn't open the box, which is counter-intuitive.
    Reviewed by gggto at 2022-05-04 12:05
  • 4. [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:

    image image image

    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

    Reviewed by sgoudham at 2022-04-26 22:48
  • 5. feat: clickable anchor links, enforce asset updates

    Following discussion here: https://github.com/tommilligan/mdbook-admonish/pull/16#issuecomment-1109179755

    This PR:

    • adds clickable anchor links from admonition titles
    • adds a mechanism for forcing the user to upgrade their installed CSS files, to allow rollout of breaking changes
      • adds notes to README, that breaking CSS changes may be rolled out on minor version bumps
    Reviewed by tommilligan at 2022-04-26 12:53
  • 6. feat: add unique ids to generated html

    Closes #15

    I investigated whether there was an easy 'click to link to this admonition', but it's not clear to me what the UX of this should be, so that's open if anyone wants to work on it.

    Reviewed by tommilligan at 2022-04-25 13:44
  • 7. 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: https://github.com/peaceiris/actions-mdbook/issues/426#issuecomment-1102752476

    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

    Reviewed by bgianfo at 2022-04-19 15:26
  • 8. 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?

    Screenshot 2022-04-29 at 17-29-31 Introduction - QEM Pratical Advanced Script Programming for Image Processing in Digital Micrograph

    Reviewed by gggto at 2022-04-29 15:33
  • 9. Add support for custom styles via directive.style

    This PR adds support for putting a custom style on an admonition.

    ```admonish note.foobar "Title"
            ...
    ```
    

    The style foobar will be added to the outer div, allow you to very easily style different blocks!

    Reviewed by schungx at 2022-02-21 01:30
  • 10. 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.

    Reviewed by schungx at 2022-04-25 06:28
  • 11. feat: make anchor links hoverable

    See discussion: https://github.com/tommilligan/mdbook-admonish/pull/26#issuecomment-1126881011

    This PR moves anchor links to a display-on-hover icon, similar to docs.rs

    This allows elements in the titlebar to have clickable actions, without confusing users.

    This PR

    admonish-link-hover

    docs.rs reference implementation

    anchor-link-hover

    cc: @schungx if you're interested in the change in this feature

    Reviewed by tommilligan at 2022-05-15 08:45
  • 12. 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
    Reviewed by tommilligan at 2022-02-20 19:21
A GitHub Action to automatically build and deploy your mdbook project.

?? deploy-mdbook The deploy-mdbook action allows you to easily build and deploy your mdBook project to GitHub Pages. See action.yml for configuration

Apr 11, 2022
unFlow is a Design as Code implementation, a DSL for UX & backend modeling. DSL to Sketch file, Sketch to DSL, DSL to code.

unflow 是一个低代码、无代码设计语言。unFlow is a Design as Code implementation, a DSL for UX & backend modeling. DSL to Sketch file, Sketch to DSL, DSL to code.

Jun 20, 2022
Add toast support in your dioxus project

Add toast support in your dioxus project

Apr 16, 2022
GitHub Actions for mdBook (rust-lang/mdBook) ⚡️ Setup mdBook quickly and build your site fast. Linux (Ubuntu), macOS, and Windows are supported.
GitHub Actions for mdBook (rust-lang/mdBook) ⚡️ Setup mdBook quickly and build your site fast. Linux (Ubuntu), macOS, and Windows are supported.

GitHub Actions for mdBook rust-lang/mdBook Setup Action. We can run mdBook on a virtual machine of GitHub Actions by this mdBook action. Linux, macOS,

Jun 23, 2022
yew-material is a material-ui framework for yew

About yew-material is a material-ui framework for yew create-yew-material-app Create Yew Material App is a way to create a single page Yew application

Jun 13, 2022
A mdbook preprocessor that allows the re-usability of template files with dynamic arguments

mdbook-template A mdbook preprocessor that allows the re-usability of template files with dynamic arguments Table of Contents Author Notes Installatio

May 3, 2022
Easy c̵̰͠r̵̛̠ö̴̪s̶̩̒s̵̭̀-t̶̲͝h̶̯̚r̵̺͐e̷̖̽ḁ̴̍d̶̖̔ ȓ̵͙ė̶͎ḟ̴͙e̸̖͛r̶̖͗ë̶̱́ṉ̵̒ĉ̷̥e̷͚̍ s̷̹͌h̷̲̉a̵̭͋r̷̫̊ḭ̵̊n̷̬͂g̵̦̃ f̶̻̊ơ̵̜ṟ̸̈́ R̵̞̋ù̵̺s̷̖̅ţ̸͗!̸̼͋

Rust S̵̓i̸̓n̵̉ I̴n̴f̶e̸r̵n̷a̴l mutability! Howdy, friendly Rust developer! Ever had a value get m̵̯̅ð̶͊v̴̮̾ê̴̼͘d away right under your nose just when

Jun 24, 2022
Rust Language Learning material

RustMaterial Rust Language Learning material Rust Rust is blazingly fast systems programming language that prevents segfaults and guarantees thread sa

Jan 6, 2022
Embedded Rust on Espressif training material.

Embedded Rust Trainings for Espressif This repository contains Training Material for learning to use Embedded Rust with the Espressif ESP32-C3. We sug

Jun 18, 2022
Jest preprocessor/transformer for Rust

rs-jest tl;dr -- see examples This is a jest transformer that loads Rust code so it can be interop with Javascript base project. Currently, the Rust c

May 19, 2022
Another cursed Garry's Mod module. This time, it adds the C preprocessor to Lua scripts

gm_cpreprocessor Another cursed Garry's Mod module. This time, it adds the C preprocessor to Lua scripts. It works by detouring RunStringEx and overri

Apr 13, 2022
mdBook is a utility to create modern online books from Markdown files.

Create book from markdown files. Like Gitbook but implemented in Rust

Jun 26, 2022
mdzk is a plain text Zettelkasten system that is based on the mdBook API.

mdzk A lovingly designed system and static publishing tool for your plain text Zettelkasten mdzk is a plain text Zettelkasten system that is based on

Jun 14, 2022
A GitHub Action to automatically build and deploy your mdbook project.

?? deploy-mdbook The deploy-mdbook action allows you to easily build and deploy your mdBook project to GitHub Pages. See action.yml for configuration

Apr 11, 2022
A backend for mdBook written in Rust for generating PDF based on headless chrome and Chrome DevTools Protocol.

A backend for mdBook written in Rust for generating PDF based on headless chrome and Chrome DevTools Protocol.

Jun 23, 2022
The open source design documentation tool for everybody
The open source design documentation tool for everybody

Heads up: reimagining artifact 3.0, check it out at artifact_py Artifact: design documentation for everybody Note: this project, and the python re-wri

May 6, 2022
A data-first Rust-native UI design toolkit.
A data-first Rust-native UI design toolkit.

Druid A data-first Rust-native UI toolkit. Druid is an experimental Rust-native UI toolkit. Its main goal is to offer a polished user experience. Ther

Jun 26, 2022
A catalogue of Rust design patterns, anti-patterns and idioms

Rust Design Patterns An open source book about design patterns and idioms in the Rust programming language that you can read here. Contributing You ar

Jun 20, 2022
unFlow is a Design as Code implementation, a DSL for UX & backend modeling. DSL to Sketch file, Sketch to DSL, DSL to code.

unflow 是一个低代码、无代码设计语言。unFlow is a Design as Code implementation, a DSL for UX & backend modeling. DSL to Sketch file, Sketch to DSL, DSL to code.

Jun 20, 2022
xh is a friendly and fast tool for sending HTTP requests. It reimplements as much as possible of HTTPie's excellent design, with a focus on improved performance.
xh is a friendly and fast tool for sending HTTP requests. It reimplements as much as possible of HTTPie's excellent design, with a focus on improved performance.

xh is a friendly and fast tool for sending HTTP requests. It reimplements as much as possible of HTTPie's excellent design, with a focus on improved performance

Jun 24, 2022