mdbook-mermaid-ssr

A preprocessor for mdbook to add mermaid.js support.

[!IMPORTANT] mdbook-mermaid-ssr provides server-side rendering for Mermaid diagrams in mdBook. Unlike the original mdbook-mermaid which uses client-side JavaScript rendering, mdbook-mermaid-ssr pre-renders all diagrams to SVG during the build process using headless Chrome.

This is not an upgrade/competition - it's a separate package with different requirements and behavior.

For the original client-side rendering version, see mdbook-mermaid.

To migrate between the two, please apply this diff:

+ [preprocessor.mermaid-ssr]
- [preprocessor.mermaid]
- command = "mdbook-mermaid"
- 
- [output.html]
- additional-js = ["mermaid.min.js", "mermaid-init.js"]

It turns this:

```mermaid
graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;
```

into this:

in your book.

Installation

From source

To install it from source:

cargo install mdbook-mermaid-ssr

This will build mdbook-mermaid-ssr from source.

Using cargo-binstall

If you have cargo-binstall already:

cargo binstall mdbook-mermaid-ssr

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-ssr executable into $HOME/.cargo/bin:

Requirements

Chrome or Chromium must be installed on the system where you build your book. The preprocessor uses this to render Mermaid diagrams to SVG.

Configure your mdBook to use mdbook-mermaid-ssr

Add the following to your book.toml:

[preprocessor.mermaid-ssr]

That's it! No JavaScript files or additional configuration needed. Diagrams are pre-rendered to SVG during the build process.

Configuration

mdbook-mermaid-ssr supports various configuration options in your book.toml:

[preprocessor.mermaid-ssr]
# Timeout for rendering operations (default: 30s)
timeout = "30s"

# Error handling: "fail" (default) or "comment"
# - "fail": Build fails on rendering errors
# - "comment": Errors are emitted as Markdown Annotations
on-error = "comment"

# Custom path to Chrome/Chromium executable (optional)
chrome-path = "/usr/bin/chromium"

# We also support all of mermaid.js options (but kebab-case instead of camelCase), such as:
# - `theme` with options: "default" (default), "base", "dark", "forest", "neutral"
# - `look` with options: "classic" (default), "handDrawn"
# - `security-level` with options: "strict" (default), "loose", "antiscript", "sandbox"
# - `font-family`
# - ... please see https://mermaid.js.org/config/schema-docs/config for a full list

Finally, build your book:

mdbook path/to/book

How It Works

1. During the build process, mdbook-mermaid-ssr launches a headless Chrome browser
2. For each Mermaid code block, it renders the diagram to SVG
3. The SVG is embedded directly in the HTML output
4. No client-side JavaScript execution is needed when viewing the book

Development

Update the bundled mermaid.js

The mermaid.js payload is managed via npm and automatically updated by Dependabot.

Dependabot will automatically create PRs when new versions of mermaid are released. The autofix.ci bot will automatically sync the payload file when the PR is created.

For local development, you can manually sync the payload by running npm install in the directory containing the npm configuration for the bundled mermaid.js.

Testing

Run the test suite:

cargo test

[!NOTE] Tests require Chrome/Chromium to be installed.

Troubleshooting

"Failed to initialize SSR renderer"

This error means Chrome/Chromium could not be found or launched. Ensure Chrome or Chromium is installed and accessible in your system's PATH.

If you need client-side rendering instead, use the original mdbook-mermaid package.

Diagrams not rendering

1. Verify your Mermaid syntax is correct using the Mermaid Live Editor
2. Check the build output for error messages
3. Ensure Chrome/Chromium is installed

Build takes a long time

Server-side rendering adds some overhead to the build process. Each diagram must be rendered in headless Chrome. For large books with many diagrams, this can take additional time. This is a trade-off for the benefits of pre-rendered SVG output.

We have not currently explored parallelization or caching strategies to optimize build times, but would welcome contributions.

License

MPL. See LICENSE.
Copyright (c) 2018-2024 Jan-Erik Rediger janerik@fnordig.de

This is a fork focusing on server-side rendering only.

Mermaid is MIT licensed. The bundled assets (payload/mermaid.js) are MIT licensed.