badboy / mdbook-mermaid

A preprocessor for mdbook to add mermaid support

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

License

MPL. See LICENSE.
Copyright (c) 2018-2024 Jan-Erik Rediger [email protected]

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

mdbook-mermaid's Issues

Making use of CDN

Hi,

I am struggling with using this plugin currently because, I don't like to put the ~3MB large mermaid.min.js into my repo, as discribed
in the installation instructions.

Is there a way to make use of the CDN network and just use the corresponding mermaid.min.js file from there on client side ?

E.g. https://www.jsdelivr.com/package/npm/mermaid

Thanks,
Peter

Error: Command:mdbook-mermaid

I followed all the installation steps however, it seems like mdbook is not recognizing the mdbook-mermaid command to render the mermaid code when serving it on localhost.

Here is a screenshot, any chance it requires a specific update?

Diagrams not being rendered

Hi! I'm a maintainer of https://github.com/esp-rs/book where we are using mdbook-mermaid. We've followed the instructions and the diagrams have been working fine for a year or so, but a few months ago they stopped working, see esp-rs/book#102. We tried updating the *.js files generated by mermaid to the latest, see esp-rs/book#90, but the issue still persists.

mermaid block code not rendered

Could not find the language 'mermaid', did you forget to load/include a language module? [highlight.js:6:14150](https://ninanor.github.io/91126800_ML_and_associated_tech/highlight.js)
Falling back to no-highlight mode for this block. 
<code class="language-mermaid">

This is how I fixed it: mermaid.init({startOnLoad:true}, document.querySelectorAll(".language-mermaid"));

I am not sure if something changed in the latest version of mdbook.

Implement dark mode support for mermaid.

Supporting dark theme on mermaid is a relatively easy fix that should be supported out of the box. All the changes required would be in mermaid-init.js, and could be changed by the end user if required.

It would be as simple as reading the class appended to the HTML field and choosing mermaid's theme accordingly before initializing it.

autonumber is broken for sequenceDiagram

Hi! :) First of all - many thanks for adding support for mermaid.js to mdBook! :)

I've been using mdbook to build a documentation for my project and I noticed that autonumber is broken for sequenceDiagram in version 8.8.4 of provided mermaid.min.js (not a js-ninja, might be wrong).

Example:

```mermaid
sequenceDiagram
    autonumber
    participant x1 as Foo
    participant x2 as Bar
    x1 --> x2: FooBar
```

I've replaced the mermaid.min.js file with https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js (which I think is 8.9.0) and now it works.

Hope this helps someone ;)

How to jump line in timeline diagram ?

How to jump line in timeline diagram ?

Mermaid version used : 10.9.0

timeline
    2014 : first line<br>second line

Loading

Expected

Actual

Maybe related mermaid-js/mermaid#4743

Codeblock character ends up in HTML

A picture says more than thousand words:

The markup used to generate this is:

This is an example page with a mermaid diagram.                                                                                                                                                                                                                                                                                
                                                                                                                                                                                                                                                                                                                               
```mermaid                                                                                                                                                                                                                                                                                                                     
graph TD;                                                                                                                                                                                                                                                                                                                      
    A-->B;                                                                                                                                                                                                                                                                                                                     
    A-->C;                                                                                                                                                                                                                                                                                                                     
    B-->D;                                                                                                                                                                                                                                                                                                                     
    C-->D;                                                                                                                                                                                                                                                                                                                     
```

Somehow, an additional codeblock-character ends up in the HTML. I don't see why.

<p>This is an example page with a mermaid diagram.</p>
<pre class="mermaid">
graph TD;
    A--&gt;B;
    A--&gt;C;
    B--&gt;D;
    C--&gt;D;
`</pre>

implement dark mode?

thankful for the library.
also the mermaid version can be updated i guess?

Hansie query - mermaid not rendering

Hi there Jan-Erik (@badboy ), hope this message finds you well. We were quite excited to find this project of yours on GitHub, as we are also using mdbook and want to start using Mermaid with it.

My structure

root                      [dir]
  src                     [dir]
    my-markdown           [dir]
      my-file.md          [file]
    theme                 [dir]
      css                 [dir]
        (default files here)
      (default files here)
    SUMMARY.md            [file]
  book.toml               [file]
  mermaid.css             [file]
  mermaid.min.js          [file]
  mermaid-init.js         [file]

In root\src\theme\index.hbs I have also added support for both equation delimiter formats as follows:

  {{#if mathjax_support}}
  <!-- MathJax -->
  <script async type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
  <script type="text/x-mathjax-config">
    MathJax.Hub.Config({
      tex2jax: {
      inlineMath: [ ['$','$'], ["\\(","\\)"] ],
      displayMath: [ ['$$','$$'], ["\\[","\\]"] ],
      processEscapes: true
      }
    });
  </script>
  {{/if}}

My test markdown code

Testing MathJax equation format 1

$$ \eta = \sum r $$

Testing MathJax equation format 2

\[
\zeta = \sum f
\]

Testing MathJax inline equation $ \beta \in [a_1..a_n] ​$ format 1

Testing MathJax inline equation \( \gamma \in [b_1..b_n] \) format 2

%% Example of sequence diagram
  sequenceDiagram
    Alice->>Bob: Hello Bob, how are you?
    alt is sick
    Bob->>Alice: Not so good :(
    else is well
    Bob->>Alice: Feeling fresh like a daisy
    end
    opt Extra response
    Bob->>Alice: Thanks for asking
    end

Loading

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

Loading

Some questions and observations

(1) mdbook-mermaid run from root does not give any success or error messages, but builds root\book
(2) Are the default mdbook subcommands supported? When I try to run mdbook-mermaid serve from root I get the message Couldn't open SUMMARY.md
(4) If I open root\book\index.html in a browser
(4.1) Equation format 1 is supported but not equation format 2 in both cases
(4.2) Mermaid does not render
(3) Do you have an example mdbook-mermaid project I can clone to test on my system?
(5) Could you possibly conceive a test for my example markdown code?

Thank you in advance.
Hansie.

Installation Fails on Mac

System

Darwin gak-8.local 21.6.0 Darwin Kernel Version 21.6.0: Mon Aug 22 20:19:52 PDT 2022; root:xnu-8020.140.49~2/RELEASE_ARM64_T6000 arm64

Expected Behavior:

https://github.com/badboy/mdbook-mermaid#installation cmd works

Steps to repro:

cargo install mdbook-mermaid

Error

error[E0432]: unresolved import `clap::crate_version`
 --> /Users/georgios/.cargo/registry/src/github.com-1ecc6299db9ec823/mdbook-mermaid-0.12.3/src/bin/mdbook-mermaid.rs:1:12
  |
1 | use clap::{crate_version, Arg, ArgMatches, Command};
  |            ^^^^^^^^^^^^^ no `crate_version` in the root

error: cannot determine resolution for the macro `crate_version`
  --> /Users/georgios/.cargo/registry/src/github.com-1ecc6299db9ec823/mdbook-mermaid-0.12.3/src/bin/mdbook-mermaid.rs:23:18
   |
23 |         .version(crate_version!())
   |                  ^^^^^^^^^^^^^
   |
   = note: import resolution is stuck, try simplifying macro imports

For more information about this error, try `rustc --explain E0432`.
error: could not compile `mdbook-mermaid` due to 2 previous errors
error: failed to compile `mdbook-mermaid v0.12.3`, intermediate artifacts can be found at `/var/folders/32/np0rcmkd3nlfnfhwwmspzjlm0000gp/T/cargo-installIWNCmd`

how can I upgrade to latest mermaid version 9.2.2 correctly?

Hi

Thank you very much for this excellent preprocessor ! Thanks again.

Here, I encountered a problem. I wanted to use the Mindmaps function of mermaid. I referred to the issue solution of #18 & #19 , replaced the 9.2.2 version of assert/mermaid.min.js, recompiled mdbook mermaid, and cooperated with mdbook. However, when I encountered Mindmaps, I would still prompt "Syntax error in graph mermaid version 9.2.2". Could you give me some advice on how to upgrade? Thanks.

Preprocessor alters the markdown in ways it shouldn't

When trying to integrate this preprocessor into my workflow, I ran into an important issue. The preprocessor removes the <> characters and does some more changes, while it shouldn't do any changes to the file since no mermaid code blocks exist. Here is an example:

Before preprocessing:

## Big-Oh Notation

Big-Oh notation is a way of calculating the maximum time an algorithm can take relative to its input size. The two ways to calculate big-oh notation is:

#### The easy way
Basically, if you have a function that consists of different versions of the **7 important functions** the one with the highest order/the one that changes with the highest values have the highest precedence. So, for example, the function <span class="katex-inline">f(n) = 2n + n^2 + 3nlog_2(n) + 2^n + 6</span> has the Big-Oh <span class="katex-inline">O(2^n)</span> since exponential functions have the highest order. 


#### The big-boy mathematical way
The formal definition of Big-Oh is:
 <span class="katex-inline">f(n)</span> and <span class="katex-inline">g(n)</span> are both functions <span class="katex-inline">\mathbb{Z}^+ \mapsto \mathbb{R}^+</span>. <span class="katex-inline">f(n)</span> is <span class="katex-inline">O(g(n))</span> if there is a real constant <span class="katex-inline">c > 0</span> and an integer constant <span class="katex-inline">n_0 \geq 1</span> that makes <span class="katex-inline">f(n)</span> less than or equal to <span class="katex-inline">c \times g(n)</span> for all values <span class="katex-inline">n \geq n_0</span>. This can be written in predicate logic as such:[^1]

  <span class="katex-display">\exists c,n_0(\forall x(x \geq n_0 g \implies cg(x) \geq f(x))) \implies f(n) \in O(g(n))</span>
 
 ![Big-Oh Graph](/Images/Pastedimage20211112111455.png)

[^1]:$f(n) \in O(g(n))$ is a more mathematical way of saying $f(n)$ is $O(g(n))$.

<div class="datetime" style="text-align: center; color: gray; font-style: italic; font-size: 90%;">21:07 Tuesday 16 November 2021</div>



<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.css" integrity="sha384-zTROYFVGOfTw7JV7KUu8udsvW2fx4lWOsCEDqhBreBwlHI4ioVRtmIvEThzJHGET" crossorigin="anonymous">

<script defer src="https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.js" integrity="sha384-ov99pRO2tAc0JuxTVzf63RHHeQTJ0CIawbDZFiFTzB07aqFZwEu2pz4uzqL+5OPG" crossorigin="anonymous"></script>

<script>
document.addEventListener('DOMContentLoaded', function() {
    var math = document.querySelectorAll("[class^=katex]");
    for (var i = 0; i < math.length; i++) {
      // Convert escaped ampersands before rendering
      var toRender = math[i].textContent.replace(/&amp;/g, '&');
      katex.render(toRender, math[i]);
    }
}, false)
</script>

---


> - [7 Important Functions](<7 Important Functions.md>)
> - [Big Omega Notation](<Big-Omega Notation.md>)
> - [Big-Theta Notation](<Big-Theta Notation.md>)
> - [Heap](<Heap.md>)
> - [String Concatantion in Java](<String Concatanation in Java.md>)
> - [Tree Traversal](<Tree Traversal.md>)

After preprocessing:

## Big-Oh Notation

Big-Oh notation is a way of calculating the maximum time an algorithm can take relative to its input size. The two ways to calculate big-oh notation is:

#### The easy way

Basically, if you have a function that consists of different versions of the **7 important functions** the one with the highest order/the one that changes with the highest values have the highest precedence. So, for example, the function <span class=\"katex-inline\">f(n) = 2n + n^2 + 3nlog_2(n) + 2^n + 6</span> has the Big-Oh <span class=\"katex-inline\">O(2^n)</span> since exponential functions have the highest order. 

#### The big-boy mathematical way

The formal definition of Big-Oh is:
<span class=\"katex-inline\">f(n)</span> and <span class=\"katex-inline\">g(n)</span> are both functions <span class=\"katex-inline\">\\mathbb{Z}^+ \mapsto \mathbb{R}^+</span>. <span class=\"katex-inline\">f(n)</span> is <span class=\"katex-inline\">O(g(n))</span> if there is a real constant <span class=\"katex-inline\">c > 0</span> and an integer constant <span class=\"katex-inline\">n_0 \geq 1</span> that makes <span class=\"katex-inline\">f(n)</span> less than or equal to <span class=\"katex-inline\">c \times g(n)</span> for all values <span class=\"katex-inline\">n \geq n_0</span>. This can be written in predicate logic as such:[^1]

<span class=\"katex-display\">\\exists c,n_0(\forall x(x \geq n_0 g \implies cg(x) \geq f(x))) \implies f(n) \in O(g(n))</span>


![Big-Oh Graph](/Images/Pastedimage20211112111455.png)

[^1]: $f(n) \in O(g(n))$ is a more mathematical way of saying $f(n)$ is $O(g(n))$.

<div class=\"datetime\" style=\"text-align: center; color: gray; font-style: italic; font-size: 90%;\">21:07 Tuesday 16 November 2021</div>
<link rel=\"stylesheet\" href=\"https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.css\" integrity=\"sha384-zTROYFVGOfTw7JV7KUu8udsvW2fx4lWOsCEDqhBreBwlHI4ioVRtmIvEThzJHGET\" crossorigin=\"anonymous\">
<script defer src=\"https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.js\" integrity=\"sha384-ov99pRO2tAc0JuxTVzf63RHHeQTJ0CIawbDZFiFTzB07aqFZwEu2pz4uzqL+5OPG\" crossorigin=\"anonymous\"></script>
<script>
document.addEventListener('DOMContentLoaded', function() {
    var math = document.querySelectorAll(\"[class^=katex]\");
    for (var i = 0; i < math.length; i++) {
      // Convert escaped ampersands before rendering
      var toRender = math[i].textContent.replace(/&amp;/g, '&');
      katex.render(toRender, math[i]);
    }
}, false)
</script>

---

 > 
 > * [7 Important Functions](7 Important Functions.md)
 > * [Big Omega Notation](Big-Omega Notation.md)
 > * [Big-Theta Notation](Big-Theta Notation.md)
 > * [Heap](Heap.md)
 > * [String Concatantion in Java](String Concatanation in Java.md)
 > * [Tree Traversal](Tree Traversal.md)

Include mermaid 8.14 in the asset?

The mermaid.js included with mdbook-mermaid is 8.9. mermaid.js is now on 8.14, any chances the included asset will be upgraded anytime soon?

Mdbook Mermaid dark mode support

Expectation:
When switching to a dark theme in mdbook the mermaid diagrams also switch to a dark theme.

What happens:
Mermaid diagrams do not honor the theme and render in light mode being not very readable in dark mode.

I am happy to help if you point me to the right start.

Wrong mdbook-mermaid configuration

I'm using mdbook 0.4.6 and I have the following book.toml file:

[book]
title = "My title"

[output.html]
no-section-label = true
mathjax-support = true

When I run this command mdbook-mermaid install . for the first time I get:

[book]
title = "My title"

[output.html]
no-section-label = true
mathjax-support = true
[preprocessor]
[preprocessor.mermaid]
command = "mdbook-mermaid"

And the book isn't build correctly.
Only when I run the command above for the second time I get:

[book]
title = "My title"

[output.html]
no-section-label = true
mathjax-support = true
additional-js =["mermaid.min.js", "mermaid-init.js"]
[preprocessor]
[preprocessor.mermaid]
command = "mdbook-mermaid"

But the best outcome would be:

[book]
title = "My title"

[output.html]
no-section-label = true
mathjax-support = true
additional-js =["mermaid.min.js", "mermaid-init.js"]

[preprocessor.mermaid]
command = "mdbook-mermaid"

Thanks in advance for your help! :)

mermaid V10 support

According to https://github.com/mermaid-js/mermaid/releases/tag/v10.0.0 mermaid has dropped the CJS support.

how can I update the mermaid.js to 9.1.1

this preprocessor is excellent!! thanks a lot!

I believe the current mdbook-mermaid 0.10 supports 8.16 , however, it is unable to render gitgraph.

may I know how can I update the mermaid.js to the latest version 9.1.1?

Use mdbook-mermaid v0.8.3 on mdbook v0.4.12

Describe the bug

When including mdbook-mermaid v0.8.3 (or latestest git version) as a valid preprocessor in the render chain controlled with mdbook v0.4.12 the process returns with ERROR.

To Reproduce

Steps to reproduce the behavior:

• compile mdbook-mermaid
• add it to the book

$ cd ~/book
$ mdbook-mermaid install

inside ~/book/book.toml the output and preprocessor tables are extended as expected. The mermaid[-init, .min].js are included.

• calling the build process

$ RUST_LOG=info  mdbook build --dest-dir=$XDG_RUNTIME_DIR/book --language en

$ 2021-09-20 11:49:40 [ERROR] (mdbook::utils): Error: Unable to parse the preprocessed book from "mermaid" processor
$ 2021-09-20 11:49:40 [ERROR] (mdbook::utils): 	Caused By: missing field `chapter_titles` at line 1 column 83887```

Expected behavior

The application should render the book with the mermaid source.

Environment

OS: Arch Linux
Rust version: 1.55.0
mdbook: v0.4.12
mdbook-mermaid: v0.8.3

Simple example from readme has an extra backtick box

Using the following markup results in the image below

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

Loading

This is on mdbook-mermaid v0.11.0

Error with mdbook-mermaid install

Looks like a clap issue with the parser. Ubuntu, brand new mdbook. Let me know if I can help debug any further.

❯ RUST_BACKTRACE=1 mdbook-mermaid install
thread 'main' panicked at 'Mismatch between definition and access of `dir`. Could not downcast to TypeId { t: 15292486789451704417 }, need to downcast to TypeId { t: 17816034824169992944 }
', /home/josephguhlin/.cargo/registry/src/github.com-1ecc6299db9ec823/clap-4.0.29/src/parser/error.rs:30:9
stack backtrace:
   0: rust_begin_unwind
             at /rustc/b70baa4f922a1809d79caeaeb902800c3be283b9/library/std/src/panicking.rs:575:5
   1: core::panicking::panic_fmt
             at /rustc/b70baa4f922a1809d79caeaeb902800c3be283b9/library/core/src/panicking.rs:64:14
   2: clap::parser::matches::arg_matches::ArgMatches::get_one
   3: mdbook_mermaid::handle_install
   4: mdbook_mermaid::main
note: Some details are omitted, run with `RUST_BACKTRACE=full` for a verbose backtrace.

how to upgrade to latest mermaid version 9.1.1?

the current version support mermaid seemed to be 8.13.10.
a number of diagram are not able to generate successfully, such as sequence, gantt, git, er, user journey.
may I know how can I upgrade from mermaid 8.13.10 to 9.1.1?

Improve installation

Right now it requires manually copying the assets and adding the right configuration.

We should add a mdbook-mermaid install command that edits the config and writes the assets (we can embed them in the binary).

Precompiled `mdbook-mermaid` executable requires newer glibc version

First of all thank you for the amazing project! :)

I recently noticed that the newest v0.12.2 release of mdbook-mermaid requires a newer glibc version if the precompiled executable attached to the github releases is used (jontze/action-mdbook#290).

This is due to the ubuntu github runner image that is used for compilation. As the deploy.yml workflow uses ubuntu-latest and github is currently in the process of rolling out ubuntu22.04 as latest runner actions/runner-images#6399.

Due to the roll out some workflows with ubuntu-latest still use ubuntu20 and others are already using ubuntu22. This repository uses already the new ubuntu22 version for the workflows.

However, all repos that are still on ubuntu20 and download the precompiled mdbook-mermaid-v0.12.2-x86_64-unknown-linux-gnu binary from the release assets are unable to use the executable as they don't have the required glibc version installed.

mdbook-mermaid: /lib/x86_64-linux-gnu/libc.so.6: version `GLIBC_2.34' not found (required by mdbook-mermaid)

Steps to reproduce

• Use a github runner with ubuntu20 (don't use ubuntu-latest as this will currently be 20 or 22 due to the roll out)
• Download the executable from the latest release https://github.com/badboy/mdbook-mermaid/releases/download/v0.12.2/mdbook-mermaid-v0.12.2-x86_64-unknown-linux-gnu.tar.gz
• Try to execute e.g. mdbook-mermaid --version

Example workflow logs:
https://github.com/jontze/action-mdbook/actions/runs/3627714992

Suggested Solution
I'm not really sure what the cleanest solution might be. In the github issue that tracks the roll out, it's mentioned to hardcode the used ubuntu version to ubuntu20 if any issues occur (actions/runner-images#6399). So to change the used ubuntu version in the deploy workflow might be a possible solution.

I saw that other open source projects also selected this approach, e.g. nushell:

• nushell/nushell#7282
• nushell/nushell#7290

Or we jut do nothing and use the following workarounds during the roll out:

• use an older release of mdbook-mermaid(before v0.12.2) if you're stuck on ubuntu20
• switch with your workflow explicitly to ubuntu22 if you want to use the latest version of mdbook-mermaid

Markdown files with CR LF line endings instead of LF do not create mermaid output

Markdown files with CR-LF line endings will only create an empty

<pre class="mermaid">
</pre>

instead of the code block.

It should be possible to verify it with the following files:
test_cr_lf.md
test_lf.md

The cause of this may be that events.into_offset_iter() in https://github.com/badboy/mdbook-mermaid/blob/main/src/lib.rs#L64
returns the mermaid content line by line instead of in one big chunk.

Mermaid update via dependabot

It seems that mermaid is quite often updated and newer versions include amazing new functionalities that I would like to use. I guess that manually checking for newer versions of the lib is not feasible nor desirable.

It would be awesome to create an npm project in this repo that contains both mermaid and the initialization code and that generates a resulting js file that is then packed as an asset in the cargo project.
In this way, one may be able to automate dependency tracking and updating via dependabot that would do that for us!

Would you be open to this idea?
Do you have any recommendations on structure and how to organize this code to not mix the cargo and npm code?

Thank you!

Mermaid Syntax Error in text on mdbook highlight

Mermaid diagram is failing on mdbook search.

How to reproduce:

Search anything on mdbook that matches the texts inside mermaid diagram. It fails with said message.

Possible keyword clashes between query param highlight

Pre-render the graphs

It would be nice to have mdbook-mermaid invoke the renderer ahead of time. Some benefits

• Syntax errors can be caught early; during the site build process.
• Probably faster as inline SVGs are probably cheaper. Loading time comes mostly from having many files, and this way we can remove the two scripts.
• No complaints from readers who have disabled javascript.

I don't know if the mermaid does anything useful that's browser dependent, or whether that'd be important. If it is, the js could still be loaded I presume, but I really don't expect that to be needed.