3 ms·

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

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

fbrchps 4y ago
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 4y ago
  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 4y ago
  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.
  - Jiocus 4y ago
    I write my .pdfs in a stand-alone markdown editor which supports mermaid, so your use-case is what I experience when doing graphs in writing. This way, there's no need to separately generate an image output to include into the document later on. Different "tools". That said, I'd love a dedicated application for diagraming, with exports to various formats for other use-cases.
Noumenon72 4y ago
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.
lmc 4y ago
I use a VS Code extension and the Live Editor: https://mermaid.live https://mermaid.live

fbrchps 4y ago

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 4y ago
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 4y ago
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.
- Jiocus 4y ago
  I write my .pdfs in a stand-alone markdown editor which supports mermaid, so your use-case is what I experience when doing graphs in writing. This way, there's no need to separately generate an image output to include into the document later on. Different "tools". That said, I'd love a dedicated application for diagraming, with exports to various formats for other use-cases.

Noumenon72 4y ago

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.

lmc 4y ago

I use a VS Code extension and the Live Editor: https://mermaid.live https://mermaid.live