For anyone interested in generating diagrams from text, I recommend also taking a look at Graphviz[1] and PlantUML[2]. Graphviz excels at box-and-arrow kind of diagrams as well as graphs, I frequently use it to visually map out dependencies, processes and state transitions, etc. There's an online version here[3]. PlantUML I use less, both because it's slower (you pay the JVM startup tax on every invocation) and because I have less use for the kind of diagrams it specializes in.
We used mermaid.js for a while. I didn't like the fact that it worked only in a browser, and installing phantom.js (which installed a whole pre-compiled binary of Chromium) was painful.
We also ran into some limitations on how we could control the final display.
So we moved all our diagrams to PlantUML and found ourselves quite happy with it.
Not "in" markdown documents but "from". In the documents the diagram markdown is rendered as itself . When exporting markdown to pdf for example, the diagram markdown is rendered as a diagram.
I’ve used mermaid for documentation, through plugins for mkdocs and Sphinx. What’s great about it is that the diagrams are stored as readable source text in the documentation, which is easy to diff and modify along with the rest of the doc (search and replace when renaming a component etc).
That’s a huge benefit compared to storing rendered bitmaps, with a source file next to them. There’s much more friction involved in keeping those up to date, the changes don’t display usefully in PRs etc. They’re almost never up to date as a result.
Another thing mermaid lets you easily do is generate sequence diagrams from code such as testcases, because the format is so simple and line-driven.
The outpout can also be included in documentation as samples, and is guaranteed to be up-to-date.
We use this to diagram our systems at a high level in documentation. It can be fiddly to get it exactly how you want it but it's a lot faster and easier to version control then, say, PowerPoint.
Has anyone managed to make decent looking org charts using Mermaid or one of the other text-based diagram generators mentioned in this thread? I've been looking for a way to make it easier for the one person we have who is working in HR to update the org chart each time we make a new hire. As bureaucratic as an org chart can be, keeping our up-to-date makes it easier for new people to figure out who everyone else is, and also helps existing staff figure out where newer employees fit in.
Sequence diagrams for one. You could probably do those in graphviz but not without serious fiddeling/invisible nodes and other tricks that would make your source far from being succinct, which is kind of the whole point
[1] https://graphviz.com
[2] http://plantuml.com
[3] https://dreampuf.github.io/GraphvizOnline/