Mermaid is particularly easy to embed in online web pages. Naturally, the most robust thing to do is generate a .png and embed that. But if you write in Markdown and have a rendering tool that directly supports Mermaid, you can add your Mermaid directly to the Markdown source that you check into git.
And even if you don't have direct tooling support for Mermaid, you can render it in the browser using JavaScript. For example:
# Finite-State Recognizers
If we're going to compile regular expressions to finite-state
recognizers, we need a representation for finite-state recognizers.
There are many ways to notate finite-state automata. For example, state
diagrams are particularly easy to read for smallish examples:
<div class="mermaid">
stateDiagram
[*] --> start
start --> zero : 0
start --> one : 1
one --> one : 0, 1
zero --> [*]
one --> [*]
</div>
Of course, diagrams are not particularly easy to work with in
JavaScript. If we want to write JavaScript algorithms that operate on
finite-state recognizers, we need a language for describing finite-state
recognizers that JavaScript is comfortable manipulating.
IMO, the best way to use it is within a format you're already checking into git, and if you can, use a tool that compiles your diagrams into an embedded SVG at rendering time.
But even if your toolchain doesn't make this easy, it's still flexible enough to get the job done.
True. In my case, I'm using Github's built-in Jekyll implementation, and I prefer to keep it as bog-standard as possible, so I went with in-browser rendering. I expect that one day many years hence, something will break and my diagrams will stop working.
One day, I should sit down and manually render them all to .png and update the markdown to use the .pngs instead. But today is not that day. Tomorrow isn't looking too good, either.
I hit this problem when trying to integrate Mermaid into a Swift Package Manager build tool. SPM sandboxes build tool access to specific folders and this causes the headless Chromium used by Mermaid-CLI to blow up.
I'm currently evaluating whether to decouple Mermaid from the browser by using a minimal fake DOM, or just rewriting it in pure Swift. It would be nice if DocC could support Mermaid in Swift doc comments.
And even if you don't have direct tooling support for Mermaid, you can render it in the browser using JavaScript. For example:
https://raganwald.com/2019/09/21/regular-expressions.html#fi...
The markdown is:
IMO, the best way to use it is within a format you're already checking into git, and if you can, use a tool that compiles your diagrams into an embedded SVG at rendering time.But even if your toolchain doesn't make this easy, it's still flexible enough to get the job done.