5 ms·
Mermaid is great for keeping simple diagrams in Markdown documents, and GitHub very recently started supporting it. Beats taking screenshots and uploading PNGs
by gepeto42 4y ago
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!
For those using VS Code, this GitHub Markdown extension also renders mermaid: https://marketplace.visualstudio.com/items?itemName=bierner.markdown-preview-github-styles https://marketplace.visualstudio.com/items?itemName=bierner....
- rockostrich 4y agoNotion also renders Mermaid code blocks inline which I've found really helpful.
- spiderice 4y agoWow! You're right. That's amazing. Definitely going to start using this.
- prepend 4y agoUnfortunately, GitHub doesn’t support it in their built-in pages Jekyll implementation.
- a4isms 4y agoTrue, but the workaround is to render the Mermaid in the browser. See: https://news.ycombinator.com/item?id=31275371 https://news.ycombinator.com/item?id=31275371
- prepend 4y agoI 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.
- a4isms 4y agoYes! 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. JM2C, YMMV, &c.
- walterlb 4y agoIt's also supported in Azure Devops wikis
- OJFord 4y agoBut 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.
- happymellon 4y agoWhy 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. That has dramatically better support.
- fuzzy2 4y agoTrying to create certain types of diagrams (e.g. sequence diagrams) in Draw.io is a huge PITA.
- mirekrusin 4y agoBecause you can't create PRs against it with readable diffs or code-generate them etc?
- mch82 4y agoExactly (though a diagramming tool could implement PRs in the future) What might be cool is a graphical editor that uses Mermaid as a file format.