Mermaid is great for keeping simple diagrams in Markdown documents, and GitHub very recently started supporting it. Beats taking screenshots and uploading PNGs to the repo for sure!
But bizarrely they chose to execute and render it from code blocks, rather than syntax-highlight it like it's an example, and use some other syntax for rendering.
For example, Latex-style formulae are usually written (for markdown renderers that support it, not GitHub) $inline$ or in $$-delimited blocks. But if you want to explain how to do that then you write `$inline$` or
```latex
$$
\foobar
$$
```
And that formats it, it doesn't execute the 'latex' (or whatever) interpreter with the contents and render its output.
Why not draw.io/diagrams.net? That used SVG which it embeds in pngs so they always render faithfully, and can be edited online, in the desktop app or directly in VS Code via a plugin.
I try to keep html and javascript out of the markdown as part of the whole point is to not make writers know that stuff. Many of the authors I work with aren’t web devs so I don’t want to ask them to copy and paste special code beyond what mermaid requires.
Instead I just use GitLab where it works great. This is just an example of GitHub being a bit behind but am hopeful that they’ll eventually come up to speed. Especially since they have it in their markdown preview.
Yes! If you're making a product for "pure" writers, I'm with you almost 100%.
That being said, Markdown has always included the ability to insert custom HTML, because Gruber wrote it to scratch his own itch. He didn't make Markdown to hide HTML from himself, he made it to do away with all the ceremony of angle brackets, which are a PITA to type and definitely make the result harder to read from source.
From a readability standpoint, I'd prefer:
```mermaid
stateDiagram
[*] --> start
start --> zero : 0
start --> one : 1
one --> one : 0, 1
zero --> [*]
one --> [*]
```
to:
<div class="mermaid">
stateDiagram
[*] --> start
start --> zero : 0
start --> one : 1
one --> one : 0, 1
zero --> [*]
one --> [*]
</div>
But I can deal with that. What discomforts me personally is the worry that something about the mermaid.js implementation will break in a future browser version.
Were I compiling to SVG or PNG as part of my build tooling, I would have a lot more trust that I could maintain a working toolchain in the future.
For those using VS Code, this GitHub Markdown extension also renders mermaid: https://marketplace.visualstudio.com/items?itemName=bierner....