mdbook-mermaid Jan-Erik Rediger
winget install --id=badboy.mdbook-mermaid -e A preprocessor for mdbook to add mermaid support
mdbook-mermaid is a preprocessor designed to integrate Mermaid.js diagrams into mdBook projects. It enables users to include charts, flowcharts, Gantt diagrams, class diagrams, and more directly within their documentation.
Key Features:
- Supports a wide range of Mermaid diagram types including flowcharts, Gantt charts, class diagrams, and ERD.
- Automatically generates HTML output with integrated Mermaid.js rendering when building your mdBook project.
- Compatible with winget for easy installation.
Audience & Benefit: Ideal for developers, technical writers, and anyone using mdBook to create comprehensive documentation. By adding visual elements like diagrams and charts, users can enhance the clarity and engagement of their content without leaving their existing workflow.
README
mdbook-mermaid
A preprocessor for mdbook to add mermaid.js support.
It turns this:
```mermaid
graph TD;
A-->B;
A-->C;
B-->D;
C-->D;
```
into this:
in your book. (Graph provided by Mermaid Live Editor)
Installation
From source
To install it from source:
cargo install mdbook-mermaid
This will build mdbook-mermaid from source.
Using cargo-binstall
If you have cargo-binstall already:
cargo binstall mdbook-mermaid
This will download and install the pre-built binary for your system.
Manually
Binary releases are available on the Releases page.
Download the relevant package for your system, unpack it, and move the mdbook-mermaid executable into $HOME/.cargo/bin:
Configure your mdBook to use mdbook-mermaid
When adding mdbook-mermaid for the first time, let it add the required files and configuration:
mdbook-mermaid install path/to/your/book
This will add the following configuration to your book.toml:
[preprocessor.mermaid]
command = "mdbook-mermaid"
[output.html]
additional-js = ["mermaid.min.js", "mermaid-init.js"]
It will skip any unnecessary changes and detect if mdbook-mermaid was already configured.
Additionally it copies the files mermaid.min.js and mermaid-init.js into your book's directory.
You find these files in the src/bin/assets directory.
You can modify mermaid-init.js to configure Mermaid, see the Mermaid documentation for all options.
Finally, build your book:
mdbook path/to/book
Development
Update the bundled mermaid.js
Find the latest version of mermaid on .
Then run:
cargo xtask
This will fetch the minified mermaid.js file and commit it.
Note: mdbook-mermaid does NOT automatically update the mermaid.min.js file in your book. For that rerun
mdbook-mermaid install path/to/your/book
or manually replace the file.
License
MPL. See LICENSE.
Copyright (c) 2018-2024 Jan-Erik Rediger
Mermaid is MIT licensed.
The bundled assets (mermaid.min.js) are MIT licensed.