[HN Gopher] Mermaid: Create diagrams and visualizations using te...
___________________________________________________________________
Mermaid: Create diagrams and visualizations using text and code
Author : tomduncalf
Score : 239 points
Date : 2022-05-05 14:27 UTC (8 hours ago)
(HTM) web link (mermaid-js.github.io)
(TXT) w3m dump (mermaid-js.github.io)
| arminiusreturns wrote:
| I'm pretty obsessed with diagrams as code and unfortunately while
| I liked the visuals produced by Mermaid I found some major
| limitations with it on my last comparison test a few months ago.
| I think it might just need to mature a little bit and then will
| probably be a solid choice. More of a greybeard sysadmin thing,
| but I usually refuse to install npm things locally so thats
| another issue for others who feel the same.
|
| What I use myself and suggest to others these days is first and
| foremost blockdiag and its variants (nwdiag, seqdiag, rackdiag,
| etc), and the very descriptive python "diagrams".
| pietroppeter wrote:
| as a related piece of new of today [0]:
|
| > The @github Markdown Preview extension for VS Code now includes
| Mermaid support!
|
| and since Nim also made front page today I will share how I added
| mermaid.js support in my very own nimib project some time ago
| [1].
|
| [0]: https://twitter.com/mattbierner/status/1522003140777701376
| [1]:
| https://pietroppeter.github.io/nblog/drafts/mermaid_diagram....
| nickmain wrote:
| Is anyone working on adding Mermaid support to Swift's DocC ?
| happymellon wrote:
| A few times a team member has tried to get everyone on board with
| Mermaid.
|
| In the end draw.io/diagrams.net wins out as embeds the diagram in
| the header of a PNG, so it can be rendered by everything and
| edited in many ways, including the web, the desktop app or the VS
| Code plug in.
| arbitrage wrote:
| Mermaid is useful for small diagrams with a few elements.
|
| When I try to create large diagrams with lots of linkages and
| text, my laptop fans kick in, and the battery starts draining. I
| use a reasonably beefy macbook pro as my daily driver.
| anoncept wrote:
| How large are the diagrams you're trying to create?
| corn13read wrote:
| tclancy wrote:
| What are you viewing the diagrams in? Maybe the problem is more
| with it than Mermaid?
| Veuxdo wrote:
| Mermaid (and plantUML) are great for simple diagrams. They aren't
| model-based though, so sharing resources across many views isn't
| possible. If you are looking for something more robust, consider
| something model-based like Ilograph:
| https://app.ilograph.com/demo.ilograph.AWS%2520Distributed-L...
| arein3 wrote:
| Ilograph looks interesting, however seems more complex than
| mermaid
| Veuxdo wrote:
| Certainly. It's definitely less quick-and-dirty and more
| focused on long-term value.
| 99_00 wrote:
| Is there any way to embed diagrams in code comments and have it
| render in any IDE or source code hosting platform?
|
| Am I wrong for wanting this?
| dmullis wrote:
| macgyverismo wrote:
| earnest question; why would I use this instead of graphviz?
| bzxcvbn wrote:
| The syntax is much simpler (albeit less powerful). It's suited
| to include in a markdown document where you don't know if the
| recipient is able to parse mermaid diagrams and ensure they get
| something readable.
| scrapheap wrote:
| I've used Graphviz for a long time and is still my first port
| of call where I need to produce the graph as a SVG or PNG.
|
| However, if I'm putting the graph into a project in
| GitHub/GitLab then I'll use Mermaid as it lets me keep it
| inline in the markdown file itself. It's also makes it easier
| for other team members to maintain that graph in the
| documentation as it doesn't require them to run additional
| tooling.
| nxpnsv wrote:
| I used it to embed graphs in a single markdown document, as
| such quite useful.
| sverweij wrote:
| mermaid (and similar diagrams-as-text tools) have a higher
| level of abstraction so they're quicker when you need something
| they're targeting.
|
| Also: graphviz is good at graphs, but not every visual
| representation is a graph (e.g. sequence diagrams, railroad
| diagrams, gantt charts).
| mdaniel wrote:
| It's the markup language supported by GitLab MR and Wiki; that
| was my first contact with it:
| https://docs.gitlab.com/ee/user/markdown.html#mermaid
|
| According to a top-level comment, GitHub also supports it, too,
| now: https://docs.github.com/en/get-started/writing-on-
| github/wor...
| prepend wrote:
| I'm such a huge fan of mermaid and use it in all my architecture
| markdown sites.
|
| I was excited when GitHub enabled mermaid in their markdown
| preview. But weird that they still don't support it in GitHub
| pages. I wish they would do this as being able to use mermaid in
| the default pages sites will be really nice. I'm currently not
| able to convince scientists I work with to set up their own
| static site generation instead of pages, just to get mermaid
| working.
| a4isms wrote:
| Mermaid is particularly easy to embed in online web pages.
| Naturally, the most robust thing to do is generate a .png and
| embed that. But if you write in Markdown and have a rendering
| tool that directly supports Mermaid, you can add your Mermaid
| directly to the Markdown source that you check into git.
|
| And even if you don't have direct tooling support for Mermaid,
| you can render it in the browser using JavaScript. For example:
|
| https://raganwald.com/2019/09/21/regular-expressions.html#fi...
|
| The markdown is: # Finite-State Recognizers
| If we're going to compile regular expressions to finite-state
| recognizers, we need a representation for finite-state
| recognizers. There are many ways to notate finite-state
| automata. For example, state diagrams are particularly easy
| to read for smallish examples: <div
| class="mermaid"> stateDiagram [*] --> start
| start --> zero : 0 start --> one : 1 one -->
| one : 0, 1 zero --> [*] one --> [*]
| </div> Of course, diagrams are not particularly easy
| to work with in JavaScript. If we want to write JavaScript
| algorithms that operate on finite-state recognizers, we
| need a language for describing finite-state recognizers
| that JavaScript is comfortable manipulating.
|
| IMO, the best way to use it is within a format you're already
| checking into git, and if you can, use a tool that compiles your
| diagrams into an embedded SVG at rendering time.
|
| But even if your toolchain doesn't make this easy, it's still
| flexible enough to get the job done.
| schemescape wrote:
| Unfortunately, Mermaid can't render to SVG without a full
| browser rendering engine. This was my biggest complaint about
| Mermaid.
|
| There is a command line tool, but it downloads a browser
| renderer.
|
| Hopefully someone will let me know if this has changed since I
| looked :)
| a4isms wrote:
| True. In my case, I'm using Github's built-in Jekyll
| implementation, and I prefer to keep it as bog-standard as
| possible, so I went with in-browser rendering. I expect that
| one day many years hence, something will break and my
| diagrams will stop working.
|
| One day, I should sit down and manually render them all to
| .png and update the markdown to use the .pngs instead. But
| today is not that day. Tomorrow isn't looking too good,
| either.
| sodality2 wrote:
| It has not!
| nickmain wrote:
| I hit this problem when trying to integrate Mermaid into a
| Swift Package Manager build tool. SPM sandboxes build tool
| access to specific folders and this causes the headless
| Chromium used by Mermaid-CLI to blow up.
|
| I'm currently evaluating whether to decouple Mermaid from the
| browser by using a minimal fake DOM, or just rewriting it in
| pure Swift. It would be nice if DocC could support Mermaid in
| Swift doc comments.
| tamiral wrote:
| I learned about this last week and I am so impressed.
| gertlex wrote:
| I come from past experiments with (py)graphviz, yed, probably a
| couple other forgotten things. (As well as manual diagrams in
| LucidChart and even Inkscape.) And am generally a non-web python
| guy.
|
| I was looking at Mermaid last weekend, since a coworker has
| praised it a few times and I was wanting to play with it.
|
| I think my expectation of how to use it was wrong? I typically
| expect to share my diagrams as .png files. The main documentation
| didn't seem to give much guidance in this usecase.
|
| I ended up going to https://github.com/mermaid-js/mermaid-cli ...
| there didn't seem to be a simple install-and-use pathway similar
| to `apt` or `pip`, so I ended up trying the docker image for it.
| I got it working to create pngs, but I thought having to mess
| with docker volume mounts and defining my own aliases (`alias
| mermaid='docker run -u $UID -it --rm -v ~/mermaid:/data
| minlag/mermaid-cli -i'` so I can do `mermaid blah.mmd` in my
| ~/mermaid folder) was a bit cumbersome...
|
| Just sharing to see if there's hot takes on where I went wrong, I
| guess. (for example, I certainly didn't extensively read the docs
| to understand the usage paradigm it's intended for)
| Noumenon72 wrote:
| I made PNGs to share because Github Enterprise doesn't display
| Mermaid as images yet, and the diagram was more than one page
| so I couldn't screenshot. I used Mermaid CLI, which brings
| along chromium and puppeteer to render images:
| npm i mermaid.cli npm i mermaid npm i
| puppeteer@latest ./node_modules/.bin/mmdc -i
| my_diagram.md -o my_image_name.png
|
| Only problem was the text overhangs the bubbles in sequence
| diagram notes.
| fbrchps wrote:
| The whole point of Mermaid is _not_ having to embed .png's into
| your Markdown files.
|
| By using the built-in codeblocks functionality of Markdown,
| Mermaid allows you to source-control the same exact graphs that
| you would have normally put in as images.
| gertlex wrote:
| That was a piece of information I missed, then! Definitely a
| nice usecase to keep in mind.
|
| For me, I'm often either (1) sharing diagrams outside of
| github (e.g. email), as well as (2) generating a bunch of
| diagrams based on code or whatever, rather than defining a
| diagram in a markdown file. There may be better tools for
| those usecases. Those were what I was trying to do last
| weekend, too.
|
| But I've definitely passed on adding diagrams to my .md
| files, or sighed at needing to add yet another imgs/ dir and
| files to a repo folder. My toolbelt now has another thing
| hanging off it!
| rout39574 wrote:
| At the cost of constraining the rendering environment, do I
| get that right?
|
| So the desire "Turn this generated graph into a diagram for
| inclusion in this PDF report" would be deemed a category
| error: my desire is wrong.
|
| It clearly makes some folks happy, but to me it's the
| antithesis of a "tool"; it's more a "website feature".
| Different strokes.
| lmc wrote:
| I use a VS Code extension and the Live Editor:
|
| https://mermaid.live
| kibwen wrote:
| It's convenient that GitHub Markdown supports graphs natively,
| and I've used Mermaid there successfully. However, I was fairly
| disappointed with Mermaid itself; I found the syntax irregular
| and non-intuitive (the syntax for every different graph type
| feels like it was designed by different people working
| independently), the documentation was sparse (though it exists at
| all, so I'll give it points for that), and worst of all the error
| messages were atrociously cryptic and entirely unhelpful.
|
| That said, I also found the default styling and layout of the
| generated graphs to be far more attractive than Graphviz/dot,
| though I'm not sure if that's attributable to Mermaid or GitHub.
|
| Which is to say, altogether probably a step forward, but still
| lots of room for improvement. Please, start with the error
| messages!
| xienze wrote:
| > the syntax for every different graph type feels like it was
| designed by different people working independently
|
| That's mostly an artifact of trying to create a DSL for wildly
| different types of graphs. A unified syntax that covers
| sequence diagrams, pie charts, class diagrams, and more
| probably wouldn't be that pleasant, so why even try. You'll see
| the same thing in PlantUML.
| PaulHoule wrote:
| Makes me think of how UML has so many subdialects for different
| diagram types.
|
| (You are supposed to be able to bootstrap all of UML from the
| very simple EMOF vocabulary but I think there are a few small
| missing pieces that make it non-trivial)
| User23 wrote:
| Interested Emacs users should check out ob-mermaid[1]. It's an
| org babel extension that lets you inline mermaid diagrams in org
| documents.
|
| [1] https://github.com/arnm/ob-mermaid
| amingilani wrote:
| I appreciate and used to use Mermaid for everything. I've since
| found PlantUML to be phenomenal. There were a few things I
| couldn't flat out do with mermaid that I can't recall since it's
| been a year. But I've never run into a limitation with PlantUML
| shafoshaf wrote:
| One thing I didn't see mentioned here is that mermaid makes
| creating charts programmatically very simple. We have a ton of
| workflows that are basically FSAs. We use Mermaid to create
| visuals of the workflows on the fly. Change it in code and the
| docs auto update.
|
| Also, VisualStudio.com supports Mermaid as well.
| aliswe wrote:
| still no topological charts though:(
| xamde wrote:
| What is a topological chart?
| aliswe wrote:
| Lets say a bunch of servers and how they communicate
| cjlm wrote:
| For something a bit more user-friendly check out flowchart.fun
| [0] - I just interviewed the sole developer [1]
|
| [0]: https://flowchart.fun/ [1]:
| https://sourcetarget.email/editions/43/
| gepeto42 wrote:
| 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....
| happymellon wrote:
| Why 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.
| mirekrusin wrote:
| Because you can't create PRs against it with readable diffs
| or code-generate them etc?
| walterlb wrote:
| It's also supported in Azure Devops wikis
| rockostrich wrote:
| Notion also renders Mermaid code blocks inline which I've found
| really helpful.
| spiderice wrote:
| Wow! You're right. That's amazing. Definitely going to start
| using this.
| prepend wrote:
| Unfortunately, GitHub doesn't support it in their built-in
| pages Jekyll implementation.
| a4isms wrote:
| True, but the workaround is to render the Mermaid in the
| browser.
|
| See: https://news.ycombinator.com/item?id=31275371
| prepend wrote:
| I 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 wrote:
| Yes! 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.
| OJFord wrote:
| But 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.
| eptcyka wrote:
| How would this be different from plantuml?
| ldiracdelta wrote:
| It has less features and less ablity to control the diagram
| than plantUML, but it is supported out of the box in a number
| of locations. Gitlab and now github.
| oicU00 wrote:
| There are Go and Python based packages for diagrams as well:
|
| https://diagrams.mingrammer.com/ https://github.com/blushft/go-
| diagrams
| fallingmeat wrote:
| Anyone know if Activity diagrams can be made in this way? (Note
| activity diagrams are not exactly flow charts, they have some
| rules)
| smusamashah wrote:
| I think mermaid also has activity diagrams. You may find a tool
| for your need in this list https://xosh.org/text-to-diagram/
| jedimastert wrote:
| My first contact with Mermaid was in Typora, and it always worked
| well enough for me.
| heycaseywattsup wrote:
| I love that GitHub and Notion both support mermaid.js now!!
|
| I wrote a tutorial for mermaid.js that you all might like :)
|
| It includes: * the most common use cases * syntax gotchas and
| mnemonics for remembering them * how to style the diagrams
| (similar to css) * options for editors (including online ones!
| https://mermaid.live rocks)
|
| Casey's Mermaid.js tutorial:
| https://www.happyandeffective.com/blog/realtime-collaborativ...
|
| ---
|
| I also wrote a tutorial for graphviz (which does not have GitHub
| or Notion support last I checked). I'm so proud of it -- it's the
| most starred graphviz tutorial on GitHub
|
| Casey's Graphviz tutorial:
| https://github.com/caseywatts/graphviz-tutorial
| sleight42 wrote:
| As well as Obsidian: https://obsidian.md/ !
| arein3 wrote:
| Obisidian has a nice variety of packages for linux (one of
| the best I've seen so far).
|
| However they don't have the simplest one (a tar.gz archive
| where you run ./app.sh from bin folder). But at least they
| have AppImage.
|
| Edit: they actually have the tar.gz option but only for arm64
___________________________________________________________________
(page generated 2022-05-05 23:00 UTC)