（评论）

（评论）
(comments)

原始链接: https://news.ycombinator.com/item?id=40981954

Graphviz 允许用户在同一直线上使用节点和边创建图形，如以下链接所示：[graphviz 示例](https://viz-js.com/?dot=ZGlncmFwaCB7CiAgYSAtPiBiIC0-IGMgLT4g...)。然而，对于复杂的图表，单独创建它们可能是有益的。与 Graphviz 不同，Mermaid 特别专注于创建软件开发图，例如流程图、序列图和类图。 Graphviz 中的图表创建需要更多自定义，包括对箭头和节点形状、线条样式和其他低级格式化元素的详细调整。相比之下，Mermaid 的设计使用了更专业的术语，例如“基数”和“可见性”，这反映了其专注于为软件工程师提供一个用户友好的环境来可视化其设计。因此，这些工具的选择很大程度上取决于每个项目的具体要求。如果您的目标是生成用于文档目的的专业软件工程图，那么 Mermaid 可能是理想的选择，因为它易于使用且具有定制功能。另一方面，如果您需要更大的灵活性或希望快速可视化非软件工程概念，那么这两种工具都可能有用。

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.

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.

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.

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.

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/

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

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

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.

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.

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.

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.

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

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.

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)

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.

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!]

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

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!]

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.

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.

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.

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.

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

（评论） (comments)

（评论）
(comments)