How we integrated mermaid with our docs

[DanielJoyce]

Hey, decided to drop a line

First we created some doc-assets

header.html:

<script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script>

after-content:

<script> mermaid.init({ startOnLoad: true, theme: "neutral" }, "pre.language-mermaid > code");</script>

the magic is the pre.language-mermaid selector. When rustdoc renders a mermaid comment, it renders it in a pre element with class of .language-mermad. So all we need to do is init the mermaid library with that selector.

Then we run rustdoc with

#!/usr/bin/env bash

set -eou pipefail

cargo rustdoc --open -- --default-theme=ayu --html-in-header=doc-assets/header.html --html-after-content=doc-assets/after-content.html

And now any comment block with a mermaid comment inside it will render graphs. This works both in item and module comments.

Once doc directives get support for html-in-header and html-after-content, the special build command can go away.

[DanielJoyce]

There is a bug in rustdoc where the first line of a included markdown file may not be rendered properly in some cases.

For now, you can add this to the top of a MD file that will be included in your docs to fix it

<!--- Do not delete this comment or the newline after, rustdoc md bug -->
<!--- https://github.com/rust-lang/rust/issues/97966 -->

The extra line MUST be present before the first line of MD Content. This is only an issue for pulling MD files, not with mermaid supprot itself.