Mermaid Gantt diagrams for displaying distributed traces in Markdown (2023) | Hacker News Reader

Mermaid Gantt diagrams for displaying distributed traces in Markdown (2023)

brycemecum.com

369 pointssurprisetalk85 comments

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 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.

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.

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?

Are you talking about lining up the pipeline symbols for columns? If it is, have you tried the AlignTab package?

I think the solution[1] used by MarkDoc is an improvement, but it does indeed start to veer towards re-inventing markup (with tag directives).

[1] https://markdoc.dev/docs/tags#table

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.

This is one area where Emacs' Org mode really shines. The tables look good even in the terminal, and the editing experience is excellent.

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.

I've been loving this service called CodeRabbit that auto generates these diagrams off my pull requests, it's fantastic -> https://github.com/jsonresume/jsonresume.org/pull/131#issuec...

And a ...poem?

That looks positively futuristic.

diagrams + poems sounds like a wonderful time in code reviews!

This looks super neat.

I didn’t see anything on the page about running the tool locally (remote code analysis is a deal breaker).

Anyone know if that’s an option?

Given it's a paid service – probably not.

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)

Yes, looks like they could be adapted to create Story Maps

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

https://files.techhub.social/media_attachments/files/112/836...

Related, we at Nunet use a GitlabCI Template to render SVGs from Mermaid files so we can reuse them: https://gitlab.com/nunet/gitlab-ci/templates/-/tree/main/mer...

This could be easily ported to Github Workflows, because the logic is very simple.

At that point you could use PlantUML (which has nicer syntax, but worse theme defaults)

I was a big Mermaid fan, but no longer.

It is very difficult to save the images as bitmap (.jpeg, .mpng) or vector (.svg).

You basically have to use a headless browser rendering toolkit, and guess what? The images aren't consistent (different rendering styles).

I'm switching to Graphviz (DOT-based) which can look just as nice and has tons of file save features.

I don’t disagree, but aren’t we actually using kind of a headless browser rendering toolkit for SVG anyway?

I was going to point to https://github.com/mermaid-js/mermaid-cli, but it uses puppeteer and chromium under the hood. That seems...excessive, to render an SVG.

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.

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.

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.

fabric.js looks interesting. We should theoretically be able to add a fabric.js based renderer for mermaid once the refactoring work is done.

https://github.com/mermaid-js/mermaid/issues/2485

Mermaid diagrams do not render correctly using the following programs and libraries:

    Adobe FrameMaker 2020
    Apache Batik
    EchoSVG
    svgSalamander
    resvg
    rsvg-convert
    svglib
    prawn-svg
    CairoSVG
    ConTeXt
    QtSVG
    MS Word
    PlutoSVG

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.

You can define nodes and edges on the same line in graphviz. Here is an example: https://viz-js.com/?dot=ZGlncmFwaCB7CiAgYSAtPiBiIC0-IGMgLT4g... Of course depending on complexity of graph you might want to do it separately.

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.

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

PlantUML also has gantt chart (https://plantuml.com/gantt-diagram ) support. unfortunately does not scale below days. There is a chronology diagram(https://plantuml.com/chronology-diagram) available but not linked from the main documentation or documented very much at all. Though it looks like the correct diagram in plantuml for the data in OP is a timing diagram (https://plantuml.com/timing-diagram)

Comically, the way I save mermaid images are through screenshots.

But this is only if I need to put it in a paper or something as otherwise just point the user to the diagram in a browser.

It is still much better than any alternative I can think of.

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)

[0]:https://mermaid.live/

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.

I've been using d2 recently [0] It's similar enough to mermaid but with the CLI you can output svg and png and have some decent looking diagrams.

[0] https://d2lang.com/

We use the mermaid gantt chart to track our releases, as well as team individuals that are out of office.

Looks like this: Out of office: [John Doe] [Stacy] Release: [code freeze] [Staging date] [Release!]

You need at least two leading spaces to get that to render as code and preserve the layout, like:

     Out of office: 
            [John Doe]
                         [Stacy]
     Release:
            [code freeze]
                           [Staging date]
                                            [Release!]

I use a google spreadsheet with 1 colum per day and 1 row per person. It looks like:

          Jan
          1 2 3 4 5 6 7 8 9 ...
  John          X X X X X
  Stacy   X X X

  Release       CF       FF

As an aside, Chat GPT is very good at giving you a baseline for mermaid diagrams given a technical spec/ hand drawn image

A simple syntax for gantt charts is a nice enough idea. But I don't understand:

1. What that has to do with markdown? I mean, that syntax isn't markdown nor does it require anything markdown-related to render AFAICT.

2. What mermaid is; the link itself doesn't explain it. I think this does, sort of:

    https://mermaid.js.org/intro/

but then - how does this relate to graphviz, or gnuplot? I'm missing that information.

3. Can I get something nice-and-compilable, not JS, for rendering these gantt charts into SVGs or what-not?

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. 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.

https://nomnoml.com/ does allow export to SVG if I remember right. But does not do GNATT Diagrams AFAIK.

I just tried the LIVE Editor: https://mermaid.live/

Yes, it does allow SVG export. Nice!

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.

That's cool! I will implement this in my block editor[1] as a new block type.

[1] https://www.get-plume.com

Yes, I'm not a pragmatic person. But the lives going right through the text, that would bother me so much if I was to regularly use this.

It bothered me too. Apparently a single CSS addition makes it more reasonable:

    .grid .tick line { opacity: 0.3; }

For those unaware, chromium has built in support for viewing trace files (obviously, not relevant if you want mermaid diagrams for documentation)

https://www.chromium.org/developers/how-tos/trace-event-prof...

It looks like though the old catapult code has been officially deprecated, and they're recommending switching over to Perfetto.

https://github.com/google/perfetto

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.

I didn't know about Mermaid. It looks nice.

This post is a little confusing, though, because this isn't markdown. It's mermaid's own markdown-like syntax for graphs/charts.

I wasn't expecting it to run client-side.

Popular (or at least relevant) markdown implementations support mermaid charts. GitHub and gitlab do, for example.

And if you use mdbook you can use the mdbook-mermaid preprocessor

https://crates.io/crates/mdbook-mermaid/

Docs:

https://docs.github.com/en/get-started/writing-on-github/wor...

https://handbook.gitlab.com/handbook/tools-and-tips/#using-m...

Docusaurus also supports it:

https://docusaurus.io/docs/markdown-features/diagrams

I've tried this exact scenario and they're really not great.

They fall down when you want to partially collapse the trace.

Mermaid supports either fully-collapsed, which will re-order your items, or not collapsed at all.