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.<p>And even if you don't have direct tooling support for Mermaid, you can render it in the browser using JavaScript. For example:<p><a href="https://raganwald.com/2019/09/21/regular-expressions.html#finite-state-recognizers-1" rel="nofollow">https://raganwald.com/2019/09/21/regular-expressions.html#fi...</a><p>The markdown is:<p><pre><code> # 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.
</code></pre>
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.<p>But even if your toolchain doesn't make this easy, it's still flexible enough to get the job done.