I think so-called ASCII-art is more in the spirit of Markdown.
The nice thing about the original Markdown (modulo bugs) is that things are written the way one would write plaintext documents which are supposed to be easily read in a text editor. So you don’t write bullet lists like this:
- Bullet 1 - Bullet 2 - Bullet 3
And hope that some post-processing will add linebreaks for you. You write it like this:
- Bullet 1
- Bullet 2
- Bullet 3
Similarily there have been many tools that let you add so-called ASCII-art diagrams to Markdown documents.
The spirit behind the kind of thing in the OP, on the other hand, is that one should get nicely formatted HTML from Markdown for the purpose of online consumption. Which is a very different goal.
So if I were to judge the syntax itself (since that is what matters most to the original spirit of Markdown.pl) I would say that it seems pretty decent. Not as “declarative” (!) as ASCII-art, but most probably much easier to edit.
The "spirit of markdown" has long been abandoned by GitHub, more often than not the offline readability of a README is absolutely ignored in exchange for a safe-HTML subset to create kind-of websites below the directory listing of a repository.
While I agree, formatting languages like Mermaid or PlantUML are human readable enough to grasp them and their meaning from reading the textual form.
And, as others below point out, editability is another great treat of Markdown. ASCII charts are very hard to format; you'll really need tools or editor plugins for that.
So I think that Mermaid (and PlantUML) strike a very pragmatic and human-friendly balance. Which, IMO is the actual spirit of Markdown.
I agree that ASCII-art definitely is more cenetered around the original markdown spirit but I personally struggle making my ASCII-art diagrams in Vim. Looking at the mermaid, syntax it looks like I can whip up something equivalent really quick. As a developer I also don't mind that the mermaid syntax reads like pseudocode so it's probably easy for me to digest.
> I think so-called ASCII-art is more in the spirit of Markdown.
If you're simply doing a less on a file, then sure. But if you want to do a 'render' on the Markdown and convert it to another format (HTML, PDF) then having a mechanism that can translate ASCII to something graphical could be useful.
In some ways this is what the DOT language does in Graphviz:
> The spirit behind the kind of thing in the OP, on the other hand, is that one should get nicely formatted HTML from Markdown for the purpose of online consumption. Which is a very different goal.
I'm not sure if there's a way to have both ASCII art and it be renderable to graphics. Closest that I could find:
One thought though, on the syntax. Wouldn’t it be a bit odd if suddenly this line in a README.md:
```js
const foo = 1 + 1
```
Rendered as:
`2`
? Isn’t that kind of what we’re doing here with the mermaid source tag? That tag is for showing source code, no? Feels like there should be another tag for rendering it.
Joplin, the Open source note-taking app¹, has Mermaid built-in.
I use those a lot when keeping my notes on arcitectures, design patterns and software design. I prefer this, vastly, over Google Docs + draw.io.
The only thing I dislike about Mermaid-in-Joplin is that the live-pre-render of the actual chart fails and shows an error whenever there is an error in the source of the diagram. Which makes sense. But is annoying because *when you are typing out the syntax, there always is an error untill you finish the class, object, some bracket or relation.
Another annoyance is how the sync between the editor and preview pane "jumps" uncontrollably when using mermaid. I do however love it too and comitted to use it over other note-taking software.
Been using in this way with Gitlab along with PlantUML for years. Slightly prefer PlantUML, feel like its a little bit more similar to native markdown due to the way it employs natural language. Would be nice if Github looked at that option too.
I don't quite understand. Does XSS mean it runs user submitted js code?
I thought it would have a parser that parses the submitted code to generate its own graph representation. there shouldn't be a chance for running js, no?
What we do at our co is run a Hugo plugin which, when an SVG is embedded in the document, provides an _Edit in https://app.diagrams.net/_ link for that SVG.
IMO, this was the missing piece for us when it came to keeping diagrams up to date.
I think this is a good change. While I would have preferred to see support for Graphviz over Mermaid, I understand Mermaid was probably chosen for the sake of easier integration. Either way, it will be nice to be able to embed diagrams rather than constantly re-generate and re-commit images to the repo.
Github will render org-mode markdown, so I've been making my documentation with it, and rendering graphviz diagrams using dot notation and org-mode's source code rendering capability. The rendered images are stored in your repo and show up inline.
I believe Mermaid supports a wider range of diagram types than Graphviz. Graphviz doesn't support sequence diagrams, for instance, unless I'm missing something.
I like the idea of mermaid.js, but why does it have to be so ugly.
I don't know why, but whenever I've had a look at mermaid.js, it always made me feel like the syntax and generated diagrams were ugly. Am I the only one who thinks this?
Also what's up with all the useless diagram types?
Yes, it is ugly. The layout engine doesn’t do ”these elements are kinda the same thing so place them side by side”. No hierarchy model, no constraints, everything is always placed on one axis according to order and then pretty much shifted randomly to not collide. Spiderwebs everywhere.
Also, ER diagrams are nigh unreadable due to the unusual relationship visual style used.
I love mermaid, but I'm also very annoyed by the variety of how its implemented in different markdown editors. One thing that I find quite annoying is the lack of fontawesome support - afaik only the live mermaid editor and hack.md supports it out of the box. Other editors require a lot of .conf file editing.
Thanks for the tip of nomnoml, didn't know about it.
In the past I used to use Mermaid for simple (but not trivial) flow charts and class diagrams.
I've found some minor rough edges, but in particular, a couple of missing features, one of which I needed (edges going from attribute to attribute in class diagrams).
PlantUML didn't have any of those limitations, so I switched, and never looked back.
For simple-but-not-trivial diagrams, I didn't find any substantial difference in terms of syntax (complexity). I don't have experience on complex diagrams, though.
PlantUML offered more decade ago. Marmaid is a toy compared to it.
However, since its so powerful, its hard to write. Actually, any given diagram is not that hard, but to keep all those syntax rules in head is IMO almost impossible.
They are quite similar, PlantUML has support for more types of diagrams than mermaid (such as network diagram), but IMO PlantUML is "messier" to write, I find Mermaid more elegant in writing diagrams.
I want a lucidchart or drawio style support for mermaid. There's plugins to let them render mermaid.md files but I haven't seen anything which just lets me draw arrows between shapes and label things. Someone please make this happen, I will be forever grateful.
Disclosure: I'm a maintainer for the project and the feature will be a bit tricky, but should be doable.
One issue is that unlike drawio, mermaid doesn't support custom placement of nodes. We could have different style arrow popups, which could render corresponding connections in default locations.
I also feel that this would be a very nice feature to have.
If anyone is interested in implementing, please let us know, and we can discuss ideas.
If you start getting into this kind of thing, you'll want to take a look at https://kroki.io which supports Mermaid along with lots of other diagramming formats.
I like markdown, and can see the lure of additions such as this one, but I also sometimes wonder whether we gained much compared to troff and its companion programs (pic, eqn, tbl, chem, etc. See https://www.troff.org/prog.html).
If we added Unicode support and html and pdf output to those, I think the main thing we would miss is readability of the raw text. That doesn’t look like much progress in half a century.
> That doesn’t look like much progress in half a century.
Considering the author of groff became the SGML expert, with SGML supporting custom syntax parsing ranging from troff-like line commands all the way to markdown or Wikimedia syntax or subsets thereof precisely for unifying ad-hoc syntax, and SGML the basis for the HTML vocabulary from which these want to run away, I'd rather say tech is re-invented in generational circles. Or devs simply like to grow mini languages ;)
[+] [-] avgcorrection|4 years ago|reply
The nice thing about the original Markdown (modulo bugs) is that things are written the way one would write plaintext documents which are supposed to be easily read in a text editor. So you don’t write bullet lists like this:
- Bullet 1 - Bullet 2 - Bullet 3
And hope that some post-processing will add linebreaks for you. You write it like this:
- Bullet 1
- Bullet 2
- Bullet 3
Similarily there have been many tools that let you add so-called ASCII-art diagrams to Markdown documents.
The spirit behind the kind of thing in the OP, on the other hand, is that one should get nicely formatted HTML from Markdown for the purpose of online consumption. Which is a very different goal.
So if I were to judge the syntax itself (since that is what matters most to the original spirit of Markdown.pl) I would say that it seems pretty decent. Not as “declarative” (!) as ASCII-art, but most probably much easier to edit.
[+] [-] daptaq|4 years ago|reply
It should really be called RENDERME.
[+] [-] berkes|4 years ago|reply
And, as others below point out, editability is another great treat of Markdown. ASCII charts are very hard to format; you'll really need tools or editor plugins for that.
So I think that Mermaid (and PlantUML) strike a very pragmatic and human-friendly balance. Which, IMO is the actual spirit of Markdown.
[+] [-] raman162|4 years ago|reply
[+] [-] throw0101a|4 years ago|reply
If you're simply doing a less on a file, then sure. But if you want to do a 'render' on the Markdown and convert it to another format (HTML, PDF) then having a mechanism that can translate ASCII to something graphical could be useful.
In some ways this is what the DOT language does in Graphviz:
* https://graphviz.org/gallery/
> The spirit behind the kind of thing in the OP, on the other hand, is that one should get nicely formatted HTML from Markdown for the purpose of online consumption. Which is a very different goal.
I'm not sure if there's a way to have both ASCII art and it be renderable to graphics. Closest that I could find:
* https://github.com/martinthomson/aasvg
[+] [-] timwis|4 years ago|reply
One thought though, on the syntax. Wouldn’t it be a bit odd if suddenly this line in a README.md:
Rendered as: ? Isn’t that kind of what we’re doing here with the mermaid source tag? That tag is for showing source code, no? Feels like there should be another tag for rendering it.[+] [-] berkes|4 years ago|reply
I use those a lot when keeping my notes on arcitectures, design patterns and software design. I prefer this, vastly, over Google Docs + draw.io.
The only thing I dislike about Mermaid-in-Joplin is that the live-pre-render of the actual chart fails and shows an error whenever there is an error in the source of the diagram. Which makes sense. But is annoying because *when you are typing out the syntax, there always is an error untill you finish the class, object, some bracket or relation.
¹https://joplinapp.org/ EDIT: I'm not affiliated to joplin in any way. Just love it.
[+] [-] wscott|4 years ago|reply
[+] [-] Ciph|4 years ago|reply
[+] [-] unknown|4 years ago|reply
[deleted]
[+] [-] milofeynman|4 years ago|reply
[+] [-] zmmmmm|4 years ago|reply
[+] [-] spacexsucks|4 years ago|reply
But lets reinvent the world in Js.. NIH is strong
[+] [-] no-dr-onboard|4 years ago|reply
Don't.
It's a sea shanty of XSS vulns.
https://snyk.io/vuln/npm%3Amermaid
[+] [-] gavingmiller|4 years ago|reply
[+] [-] DiabloD3|4 years ago|reply
[+] [-] Someone1234|4 years ago|reply
[+] [-] billconan|4 years ago|reply
I thought it would have a parser that parses the submitted code to generate its own graph representation. there shouldn't be a chance for running js, no?
[+] [-] unknown|4 years ago|reply
[deleted]
[+] [-] eminence32|4 years ago|reply
[+] [-] luxurytent|4 years ago|reply
IMO, this was the missing piece for us when it came to keeping diagrams up to date.
[+] [-] creakingstairs|4 years ago|reply
[+] [-] jonpalmisc|4 years ago|reply
[+] [-] nanomonkey|4 years ago|reply
[+] [-] djur|4 years ago|reply
[+] [-] WalterGR|4 years ago|reply
[+] [-] jopsen|4 years ago|reply
I don't know why, but whenever I've had a look at mermaid.js, it always made me feel like the syntax and generated diagrams were ugly. Am I the only one who thinks this?
Also what's up with all the useless diagram types?
[+] [-] eurasiantiger|4 years ago|reply
Also, ER diagrams are nigh unreadable due to the unusual relationship visual style used.
[+] [-] lpghatguy|4 years ago|reply
I remember the docs for Mermaid.js talk about varying document trust levels, which is not something I want involved in a diagramming DSL.
[+] [-] mafro|4 years ago|reply
For example, https://github.com/mafrosis/step-ca-on-rpi#sso-for-ssh
I'd usually commit the source .monodraw files to the repo, but for some reason I didn't in that example repo :/
[+] [-] ak217|4 years ago|reply
My wish is for Mermaid and nomnoml to become universally supported among Markdown web renderers (I'm looking first and foremost at Github of course).
[+] [-] KaoruAoiShiho|4 years ago|reply
How does nomnoml compare? The results are with mermaid are not ideal for me.
Edit: That one above is actually relatively decent. The results with mermaid can get a lot worse, actually to the point of uselessness.
Terrible examples below
https://fiction.live/stories/The-Hypno-Games/eSSzPJ6qiqAC746...
https://fiction.live/stories/The-Gynarchy/czyGfAtJpRgtzGFmW/...
[+] [-] Ciph|4 years ago|reply
Thanks for the tip of nomnoml, didn't know about it.
[+] [-] mongol|4 years ago|reply
[+] [-] pizza234|4 years ago|reply
I've found some minor rough edges, but in particular, a couple of missing features, one of which I needed (edges going from attribute to attribute in class diagrams).
PlantUML didn't have any of those limitations, so I switched, and never looked back.
For simple-but-not-trivial diagrams, I didn't find any substantial difference in terms of syntax (complexity). I don't have experience on complex diagrams, though.
[+] [-] majkinetor|4 years ago|reply
However, since its so powerful, its hard to write. Actually, any given diagram is not that hard, but to keep all those syntax rules in head is IMO almost impossible.
[+] [-] Ciph|4 years ago|reply
[+] [-] MrTortoise|4 years ago|reply
[+] [-] ghostoftiber|4 years ago|reply
[+] [-] sidharthv|4 years ago|reply
Disclosure: I'm a maintainer for the project and the feature will be a bit tricky, but should be doable.
One issue is that unlike drawio, mermaid doesn't support custom placement of nodes. We could have different style arrow popups, which could render corresponding connections in default locations.
I also feel that this would be a very nice feature to have.
If anyone is interested in implementing, please let us know, and we can discuss ideas.
[+] [-] zellyn|4 years ago|reply
[+] [-] kkirsche|4 years ago|reply
[+] [-] chrisweekly|4 years ago|reply
[+] [-] Someone|4 years ago|reply
If we added Unicode support and html and pdf output to those, I think the main thing we would miss is readability of the raw text. That doesn’t look like much progress in half a century.
[+] [-] tannhaeuser|4 years ago|reply
Considering the author of groff became the SGML expert, with SGML supporting custom syntax parsing ranging from troff-like line commands all the way to markdown or Wikimedia syntax or subsets thereof precisely for unifying ad-hoc syntax, and SGML the basis for the HTML vocabulary from which these want to run away, I'd rather say tech is re-invented in generational circles. Or devs simply like to grow mini languages ;)
[+] [-] 2wrist|4 years ago|reply
Also on Azure DevOps too https://docs.microsoft.com/en-us/azure/devops/project/wiki/w...
What a time to be alive! :-)
[+] [-] Brian-Puccio|4 years ago|reply
https://about.gitlab.com/releases/2017/12/22/gitlab-10-3-rel...
[+] [-] hobo_mark|4 years ago|reply
[+] [-] stakkur|4 years ago|reply
[+] [-] emj|4 years ago|reply
Also The Arte of ASCII RFC8140 https://datatracker.ietf.org/doc/html/rfc8140