I've used mermaid from within markdown before, but the whole premise still leaves me conflicted. The original selling point of markdown is that it wasn't a markup language; it was readable text that could optionally be rendered with some extra niceties if you were reading it in something more sophisticated than a simple text field. While mermaid is undoubtedly useful as a textual language for describing graphs, the spirit of markdown would favor something that actually looked like a graph without needing to run it through a renderer, something more akin to ascii art, but with well-defined semantics such that it would produce something reasonable if you did have a renderer at hand.
While I agree in principle, in practice the result would probably be terrible.
Just look at tables in GFM, which mostly were designed as you propose. They look like tables even before rendering, however the experience of actually creating and editing the tables is not fun at all.
I have a horse in this race (co-founder of a markdown-based note-taking app) and to me, the benefit of markdown is easy + explicit editing, not that it looks the same in plain text vs rendered.
I agree with you on Markdown tables. They're pretty horrendous to write by hand. I wonder if there's an alternative that would be easier? Maybe something that's essentially a CSV embedded in a Markdown file? I'm sure CSV has some edge cases that could be a problem, but it's probably a decent 80/20 (or better) solution if you just want to make a quick table by hand.
CSV are no better than markdown tables to edit by hand. However they’re convenient in that you don’t have to do that and can use a spreadsheet.
rST allows using a csv as a table and that’s mighty convenient. An other thing that’s mighty convenient is rST allows rendering a nested list as a table. It’s not amazing because each list item is a row rather than a column, but it is a lot less confusing than having to edit a markdown table if you’re not in a table-aware editor.
Worth noting that Emacs makes Markdown tables pretty easy to create and format cleanly for plain text viewing, and other editors may/could/should do the same.
I use Sublime almost 100% now-a-days; and, it for sure isn't as nice as Emacs for editing MD tables, but multi-cursor editing does about 80% of the heavy-lifting for MD tables. I guess I could conjecture someone objecting about "really big" tables and editing them ... but, is MD really the right choice in that case?
I personally think the bottom line here is that markdown simply isn't intended nor well suited for anything complex such as tables or diagrams or any such things that have been bolted on afterwards.
Yea, I have to agree. I don't agree with the title. It may be convenient to put Mermaid Gantt diagram SPECIFICATIONS in a Markdown document, but they are not great for displaying the Gantt charts in Markdown.
To me a more accurate title and summary of the article is "TIL: Mermaid Gantt diagram specifications can be embedded and processed in Markdown documents".
You might want to have a look at svgbob or typograms then. I used the former for creating diagrams for a guide on Git and it worked really well. Of course Markdown editors could be better at "drawing" things, which would solve the pain in creating these diagrams.
> (...) the spirit of markdown would favor something that actually looked like a graph without needing to run it through a renderer, something more akin to ascii art, but (...)
I completely disagree. The spirit of Markdown is to provide something that is a user-friendly, simple and easily works on most cases. The spirit of Markdown is not to bear with substandard, unreadable, and outright unfriendly documents just because ineffectiveness and lack of support for basic features is wrongly interpreted as simplicity.
Markdown supports images. Mermaid is nothing more than a way to simplify how developers can put together and maintain images without requiring specialized editors or additional software.
I wonder how much effort it would be to put together something expanding on this that's really friendly to new developers exploring a system. The goal would be to have something that looks more like a traditional swimlane diagram, but with human readable labelling of the connections. The open telemetry data should provide a nice skeleton and then maybe use some LLM summarisation (with access to the source code) to label what's going on.
There are local code <-> LLM interfaces though (CLI tools, editor extensions), and if you can figure out a suitable prompt you can get pretty similar experience. (Of course, you'll also want to run an LLM locally as well)
I love diagrams to represent how systems are setup and run. At one employer, they had hundreds of spreadsheets around the network drive which often linked together via formula or VBA code, along with queries out to databases.
I built a file parser (in VBA, because that is what was available) to log every file reference to a big table, the generate graphviz code to visualize it.
It's easy to say "tons of stuff uses $datasource", but it's way better if you can show exactly how much and the impact of changes.
It was incredibly useful when we changed our domain and all network drive mappings broke.
I was interested to see what this would be like applied to ansible job events coming from automation controller/awx so I put something simple together. I kind of like the tracelike visualization and might use it somewhere
We are doing some fundamental changes to how diagrams are rendered, which would enable us to support more renderers. This will enable us to do server side rendering without a browser.
The main reason why we need a browser currently is size calculations of the SVG boxes, which libraries like jsdom does not support.
Please don't take the, in my opinion, excessive criticism to heart. Mermaid is fantastic. It would be even better if it supported more renderers but as it stands to day its an invaluable tool.
That I can bring GraphViz into a browser but not Mermaid out of the browser forces GraphViz for some usecases. Unless browser-native was the intent (idk, it could be... maybe thats why it was named Mermaid), I do think it should be a high priority thing.
FWIW I gave up trying to render SVG for our project and switched to using fabric.js (and node-canvas for server side rendering). For us it was mostly because it had far better text support.
SVG is in a bit of an awkward place. It’s mostly used as a graphics file format. It actually is (when opened by a web browser) a full application environment, the nonreflowable counterpart to the reflowable HTML, or the open version of Flash with worse authoring tools: there’s support for full JavaScript, MathML, CSS, animations without CSS... You can probably stick RDFa somewhere in there too. And while XML is outwardly simple, I’ve heard an XML parser author say Adobe tools exporting SVGs like to define parsed entities in the internal DTD subset (did you know XML inherited a full textual macro system from SGML?).
There’s a reason why there’s SVG then there’s SVG Tiny then (recently, not approved by any standards process) there’s SVG Tiny PS. But as far as I can tell, there still isn’t any broad agreement on what subset of SVG is sane for dumb graphics consumed by (relatively) dumb rasterizers.
This is interesting, but we're not expecting Mermaid to parse and execute SVG content, we just need it to export its internal representation to SVG.
IIRC the issue is that they rely on DOM manipulation for rendering (and node doesn't have a DOM). I can't think of a reason why Playwright as a mechanism would result in inconsistent output though, as long as you give the CLI the same theme/size/etc parameters as the original.
May I suggest my favorite: blockdiag (including seqdiag, nwdiag, and actdiag, and rackdiag (rackdiag super slept on!))
I've evaluated every diagrams-as-code tool in existence just about, and revisit them every year or two, and I keep coming back to blockdiag. Mermaid looked nice but had many issues I ran into.
blockdiag doesn't look as pretty out of the box, but when done right it looks really good, especially as an SVG
When I have needed a static image I have just taken a screenshot. I would still put the mermaid code and style next to it in case future modifications were needed. Worked reasonably well.
Graphviz is hard. I only need a graph making tool three or four times a year and when I go back to mermaid, only 5 minutes of going through the documentation get's me up to speed. But graphviz is much more complex in a way I often don't need. It's also pretty verbose; You first need to define nodes then the connections while in mermaid both are done in a single line.
However mermaid's experience and output is definitely subpar. Under the saved graphs section you find randomly saved graphs and there is no way to organize multiple graphs in the web editor.
I've even thought of writing a simple script to translate mermaid charts into dot language.
A potentially much bigger difference in verbosity comes from graphviz being a general purpose graph drawing software, while mermaid is more of a software for drawing software development related diagrams (not just graphs and tables). This is well reflected by the fact that in graphviz the diagram types are categorized by layout engine (hierarchical drawing, spring model, force directed placement, circular layout,...), but in Mermaid they are categorized by what data the diagram represents (flowchart, sequence diagram, class diagram, state diagram, entity relationship diagram, gant diagram). You can draw many of those types of diagrams in Graphviz but you will have to potentially do a lot more of reinventing the wheel and low level manual formatting (arrow and node shapes, line style, etc.), while Mermaid documentation uses more of diagram specific terms like cardinality, visibility(public, private, ...) and many others.
That's like comparing Excel with purpose built accounting software or an inventory management system. Excel might be a lot more flexible, but if the usecase specific software matches your needs it can be a lot more streamlined and less error prone.
So the conclusions will very much depend on your use case. If you are trying to draw one of the standard software engineering diagrams as part of design documentation, Mermaid can be great. For less formal design diagrams or quickly visualizing the state of some algorithm it's much more even playing field.
The thing that's problematic is rendering Mermaid SVGs outside of a browser environment - i.e. what static site generators need in order to generate JS-free HTML docs from Markdown content.
If you're looking at a rendered Mermaid diagram on your screen, you probably already have the SVG in your browser's dom. You can just right click -> view source -> find element -> view as html -> save that to a file. I expect this is how the SVG export on the Mermaid live editor[0] works.
(the Mermaid live editor is great, it's where I tend to go if I want an SVG export)
I work on Scroll (https://scroll.pub), which currently compiles to HTML/TXT et cetera.
Compiling to JPG, SVG, PDF, MKV, MP4, et cetera, are high on my todo list, but I really haven't seen a standout way to do that, beyond that would run through Chromium.
I wonder if Ladybird (https://ladybird.org/) might be appropriate for that use case? Not sure if it's a new rendering engine or what.
>It is very difficult to save the images as bitmap (.jpeg, .mpng) or vector (.svg)
Huh? It's quite trivial, and even some tools for VS Code and other environments support it.
>You basically have to use a headless browser rendering toolkit, and guess what? The images aren't consistent (different rendering styles)
Is your problem saving Mermaid as images or lamenting cross browser rendering consistency?
If it's the former, why is the latter a problem? Use a single headless browser rendering toolkit and stick with it. Who said you need to use multiple and compare?
And there are other ways to do it, like exporting from an actual in-browser render, or even a VS Code extension - it can also be found in other tools based on Electron.
Not a complete answer to your question, but Mermaid is a plain-text diagram format which, while far from perfect, is supported by Github. So if you're looking to include a simple chart in your Readme or Markdown docs, it's a good choice.
1. In markdown you can specify a language to perform syntax highlighting within code blocks -- e.g. ```java ... ```. If you use "mermaid" there you can get the mermaid plugin to render that block. This is useful when providing a system overview, etc. in a project readme file.
2. Mermaid is a diagram rendering tool similar to graphviz and D3.js. It uses a different syntax for each chart type with the intention of making it easy to write and to read when looking at markdown source.
3. You would need to use a separate program like graphviz to do the layout and generate an SVG, PNG or other file that you can reference in your markdown or other document files. If/when mermaid provides a similar capability you'll be able to use that instead.
#1. mermaid is a syntax for diagrams that is markdown native, in that it is designed to be fit well in MD, and shares goals like ex. a progressive upgrade from text to render that is readable in either format
#2. Graphviz and gnuplot also render diagrams
#3. Sort of like asking if you can get a Markdown renderer in not JS: most direct answer is yes. If the Q is more "can Mermaid be rendered as SVG?", yes, the render format is SVG
I should have probably written: Something portable and compilable to a small(ish) Unix/Windows dynamic library with an associated C header, which takes the Mermaid input and produces some kind of vector graphic output like SVG. So it can be used basically everywhere and with everything.
So anyhow, I just learned about the perfetto switch, so I won't try and dig up a link to the old way of formatting your traces to work with chrome://tracing, as it sounds completely deprecated. Go use Perfetto if you want a fairly easy way of interacting with trace data. I assume it's at least as good and useful as chrome://tracing.
There’s a CLI [0] that outputs html, alternatively you can encode the markwhen text as base64 and append it as a hash to timeline.markwhen.com which will render it. Would look like timeline.markwhen.com#mw=[base64 encoded text]
This blog post doesn't mention it, but the tweet that it links to contains the more interesting point: GitHub markdown supports automatically rendering these mermaid diagrams.
Ha, I was pondering the exact same question after reading this, for this use-case and in more widespread sense. I've came to the conclusion that it's a form of outsourcing your costs. The clients want to view your charts? They pay for it with their electricity, instead of your server doing handouts for everyone.
I think that the point is to be easy to be changed, since Mermaid's first use case is to be used in building diagrams/graphs with data fetched at runtime like telemetry or finances data. I guess you can probably use Mermaid and take the resulting html and add it to the resulting document if you really want.
