Include diagrams in your Markdown files with Mermaid
github.blog
github.blog
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.
here-in is the nub. these are self contained(/embeddable?) editors of what is essentially non-textual content. there's a concealed inner data-model which is rendered/transpiled into text.
i far far far far prefer a text mark up, which is easy to directly edit, which is fairly readable on it's own (imo mermaid reads very nicely). maaking the inner data model both explicit directly workable like this is ascendant beyond compare.
mermaid also has predictable rendering rules, where-as there's much more author's opinion/whim about crafting ascii-diagrams, which are open ended. this makes it more predictable as a reader, with diagrams following common layout & flow patterns that one can come to expect.
the other boom to mermaid is it's not that hard to parse. i have investigated how available the mermaid team makes the parser but having a relatively-simple well-specified machine readable format opens so so many doors.
absolutely the right choice using human editable text markup inside human editable markdown.
It should really be called RENDERME.
Hah—yes!
Markdown was meant to be rendered, not left as plaintext (for viewing, at least as a primary use-case). It's name is a punny joke, but it's a lightweight markup language that was meant to be a lightweight way to write formatted text that would be rendered as formatted HTML. GFM seems in keeping with this for the most part.
No, that was not the primary design goal.
> The overriding design goal for Markdown’s formatting syntax is to make it as readable as possible. The idea is that a Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions. While Markdown’s syntax has been influenced by several existing text-to-HTML filters, the single biggest source of inspiration for Markdown’s syntax is the format of plain text email.
Literally the first paragraph from your link. I'm having trouble reconciling that first paragraph with the idea that it wasn't meant to be rendered as HTML.
If you just want plaintext, then you don't need markdown or any other markup. Just a plaintext file, like, I don't know, a README file. Don't throw .md (or .org in my case) on it, and it won't get rendered.
No, from day 1 it was meant to be readable as plain text and optionally rendered as HTML
Nobody is disputing that a key requirement of MD is to be machine parseable. What you’re missing is that another key requirement is for it to be human readable in plain text because it needs to be readable even when it hasn’t been rendered. Ie the rendering is an optional step but the format has to support one’s choice whether to render.
The argument that GitHub is abandoning the "spirit of Markdown", I surmise, is that a README file written in Markdown should be equally readable whether you're reading it as rendered HTML or not. It may be a minor quibble in some respects, but I think it's a valid minor quibble. If I open your README file in my editor, I shouldn't have to run it through external software to make it comprehensible. I mean, maybe your project has an awesome logo, but would you just drop SVG code in the middle of the README file and tell me that if I was using the proper rendering engine it wouldn't be profoundly annoying? No, of course you wouldn't, because you're not a jerk. :)
Personally, I try to use only the "reference" style of links in README files so they look like "footnotes" when read as plain text, try not to include images unless they're both supplemental and really helpful when rendered on GitHub (e.g., screenshots for editor themes), etc. Mermaid seems like it would be awesome for generating diagrams for finished pages, but it doesn't seem at all like a good fit for READMEs.
You wrote:
> Markdown was meant to be rendered, not left as plaintext
Then the overriding design goal would not be to make it “as readable as possible” in its “raw” form (because what would be the point of that?). So this is clearly a falsehood.
Markdown was meant to be readable as-is. Meaning that you could read it as-is or render it. At your leisure.
Also literally your words:
> was meant to be a lightweight way
With the overriding goal of making it “as readable as possible”. Keyword “override”. Which means that it takes precedence over being “lightweight”.
Then you literally wrote:
> that it wasn't meant to be rendered as HTML.
Clearly a falsehood or a strawman as I only emphasized the “overriding design goal”. Markdown was supposed to be able to be rendered as HTML… and to be readable as-is.
The part that you were wrong about was this:
> Markdown was meant to be rendered, not left as plaintext
It was designed to be readable as plaintext as well… so this assertion of yours is false since it implies that plaintext readability was not a consideration. But it was in fact the primary design goal when making the syntax.
I hope this clears things up.
I wish they wouldn't have used code blocks though - I commented on this recently about some other plugin that was doing it: usually ``` gets syntax highlighted and 'pre' formatting, but otherwise its contents is unchanged; it's unusual to execute the contents.
```python
print(42)
```
print(42)
42
In my opinion it would've been better to use $$ as often used for mathjax, $$mermaid or something. Since it is expected that an interpretation of
$$
\code\here
$$
```tex
\code\here
```
> Markdown’s syntax is intended for one purpose: to be used as a format for writing for the web. [1]
[1] https://daringfireball.net/projects/markdown/syntax#html
Now it’s not. Markdown was intend to be legible in plain text but visually emulate rendered text. The rendering stuff came later but even then it still had an emphasis on plain text readability.
There is a reason it was chosen for README, INSTALL etc documents in project repositories that are (or, at least until relatively recently in computing history, were) traditionally read in the command line.
> The rendering stuff came later
Here is the original announcement I was able to track down:
http://www.aaronsw.com/weblog/001189
> For months I’ve been working with John Gruber on a new project. The idea was to make writing simple web pages, and especially weblog entries, as easy as writing an email, by allowing you to use much the same syntax and converting it automatically into HTML.
Seems that HTML rendering was there from day 1.
This is what Aaron meant when he said:
> as easy as writing an email, by allowing you to use much the same syntax
…in that link you’ve posted.
Heck, even that quote token I used above (the greater than prefix) is a really old convention used in emails since probably before Aaron was even born.
It’s also worth noting that when markdown was released there were plenty of other plain text mark ups around (there’s some not even mentioned in that blog post too) but both Greg and Aaron point out that markdown is more readable in plain text and that’s a key decision behind it.
The examples shown in the fine article are Hello, world. The information contained within would be just as clear in vulgar prose. However the Mermaid code to create complex flowcharts that are not easily described in words, would be just as opaque as the Netscape 5 codebase.
My issue is that you can still have a nice readme (often even giving a better, brief overview) by sticking to HTML-free Markdown.
Gitlab seems to be slightly better than Github, by allowing things like badges to be listed outside of the README, in the header of the repository page.
This always irked me as I can't read the image when trying to look at raw text and the, say build status, isn't actually relevant to understanding the project. Sourcehut has an interesting approach where you can POST any HTML to an endpoint at it becomes the homepage. You can tag on extra markup if you want in the build step and that markup doesn't have to live in the README (say badges, other images, abbreviation tags, summary/details, etc.)
* reading documents in the terminal (like man pages)
* note taking
In both those instances the less auto-formatting that the editor does the easier it is for me to use the use the file format.
I’m sure you can say that editor auto-formatting isn’t an issue because people manage fine on MS Word. But the point is I want as little distractions as possible when not taking but I also want to be able to add headings and code snippets. So wrestling with an editor when it gets its formatting rules in a mess is the exact opposite of productively. Eg take a look at the number of authors that still use DOS editors for similar reasons.
If you want a simple README, then do a README and not a README.md.
“Markdown is a text-to-HTML conversion tool for web writers. Markdown allows you to write using an easy-to-read, easy-to-write plain text format, then convert it to structurally valid XHTML (or HTML).”
⇒ I think “easy to read and write” is an important, but secondary goal. The goal is to render to (X)HTML.
That’s similar to how SwiftUI’s
struct ContentView: View {
var body: some View {
Text("Hello World")
}
}
JFrame frame = …
JLabel label = new JLabel("Hello World");
frame.getContentPane().add(label);
> The overriding design goal for Markdown’s formatting syntax is to make it as readable as possible. The idea is that a Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions.
This also fits with the ordering from the second paragraph:
> Thus, “Markdown” is two things: (1) a plain text formatting syntax; and (2) a software tool, written in Perl, that converts the plain text formatting to HTML.
Markdown has always included rendering capability as a goal but I think GP is right, Markdown was never intended to be an always render first format just because it included the capability to render.
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/ivanceras/svgbob
* https://github.com/ggerganov/dot-to-ascii (renders DOT to ascii. Combine this with an SVG renderer, maybe?)
* https://github.com/ivanceras/spongedown
Also, this SO question: https://stackoverflow.com/questions/3211801/graphviz-and-asc...
I'm sure there are more out there.
Or maybe MacOS only? I dunno. Definitely doesn't feel snappy and certain things just don't work.
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.
Even with tools and plugins, creating tables in Markdown (in any flavor) is painful enough that I just don't even try. No one really expects to edit an image with a text editor but tables are tantalizing close.
I'd sooner have ASCII inspired tables that are easier to edit than images and diagrams.
My main reason for writing it was for inclusion in markdown documents.
Personally _I_ even sometimes use them when markdown isn't available, as in won't be rendered.
Used in zeromq docs.
The spirit of Markdown is succinctly described on DF's Markdown project website.
"Markdown allows you to write using an easy-to-read, easy-to-write plain text format."
Mermaid makes it easy-to-read and easy-to-write. ASCII is easy-to-read, but hardly easy-to-write. While Mermaid isn't as nice-to-read, it's still easy-to-read. It's also much easier to modify than ASCII art.
Finally, Markdown itself was designed that while the text is easy to read, Markdown itself is a conversion tool. It literally takes the text and changes it into something that is more readable. This can be seen with how Markdown handles tables. It's literally HTML table tags rather than ASCII designed tables.
This is very much in the spirit of Markdown, and things like this have already been done in the original implementation.
> "Markdown allows you to write using an easy-to-read, easy-to-write plain text format."
The third/fourth person to quote the original article while failing to acknowledge this paragraph from the same article:
> The overriding design goal for Markdown’s formatting syntax is to make it as readable as possible. The idea is that a Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions.
Your quote brings up two things that might be in conflict sometimes:
1. Being easy to write
2. Being easy to read
Given that the “overriding design goal” (my emphasis) is to be as “readable as possible”, it immediately follows that (2) takes precedence over (1). Which is why you assertion here:
> While Mermaid isn't as nice-to-read, it's still easy-to-read. It's also much easier to modify than ASCII art.
Misses the point—the original spirit is to be easy to read, and that does (by implication) take precedence over being easy to write.
if i was to have a graph view thats equally readable when not rendered, id want the barebones bits of graph viz's dot syntax
> Markdown is a text-to-HTML conversion tool for web writers. Markdown allows you to write using an easy-to-read, easy-to-write plain text format, then convert it to structurally valid XHTML (or HTML).
Inventor of Markdown
> The overriding design goal for Markdown’s formatting syntax is to make it as readable as possible. The idea is that a Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions.
So a text-to-HTML conversion to with the overriding design goal of being readable as-is… that’s the Gruberian spirit, and the basis for my original post.
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
```
`2`
Some tools in the computational notebook space use markdown with fenced code blocks as blocks of executable code, see for example jupytext: https://github.com/mwouts/jupytext/blob/main/docs/formats.md or myst markdown: https://myst-parser.readthedocs.io/en/latest/syntax/syntax.h... or nbconvert: https://nbconvert.readthedocs.io/en/latest/
What’s debatable is what the spec does with the “info” section.
```ruby
# syntax highlighted as ruby
a = 1 + 1
```
```js
// syntax highlighted as js
a = 1 + 1
```
```!ruby
# evaluated
as ruby
a = 1 + 1
# renders 2 because of implicit return?
```But in the end went with simple. There will be a very limited subset that will render this way - executing raw code without the users permission in the browser just opens up too much attack surface area that we’d need a very compelling use case to do the security work necessary to make it protected (even if that was possible)
But for "markdown the language" having a standard syntax for embed/evaluate along with prettify/highlight would've been nice - effectively a standard markup for multi-language "notebooks"/literate programs (maybe we need a triplet: format, render/embed, transclude/literate programming).
Github could then opt-in to highlighting the N languages they do, and initially only try to render mermaid graphs. Then perhaps also graphviz graphs. Etc.
[1] I'm sure one could do some minor DOS at least with a 500 mb graph..
<pre><code> your mermaid code <span class="foo">with highlighted</span> sections </code></pre>
Use a tool like pygments to generate the highlighted HTML (assuming there even is highlighting for mermaid syntax).
What you're asking for is an uncommon edgecase that's not what people want in 99% of circumstances (instead they want the rendered chart). Markdown still gives you the HTML escape hatch so use it. Sure it's not pretty but it's no worse than if github didn't support highlighting mermaid source anyways.
If you don't want highlighting just put a fenced code block without the mermaid info string. It will render as unhighlighted code. IMHO that's what you'd want as a workaround to demo source like in a mermaid readme.
It's how it worked before this change, and how it works for every other language in Markdown. This is taking away functionality with no reasonable replacement and creating a special-case gotcha in the Markdown syntax (the same syntax could produce highlighted code or a rendered image depending on the language and what features any particular Markdown implementation supports), and it's not clear why this is necessary when something like ```!mermaid would work just as well to trigger rendering. It's unforced bad language design.
> Use a tool like pygments to generate the highlighted HTML
This requires hardcoding colors into the generated HTML, so the highlighting won't match the color theme of the context that the document is embedded in, breaking e.g. dark mode.
https://squidfunk.github.io/mkdocs-material/reference/code-b...
``` py hl_lines="2 3"
def bubble_sort(items):
for i in range(len(items)):
for j in range(len(items) - 1 - i):
if items[j] > items[j + 1]:
items[j], items[j + 1] = items[j + 1], items[j]
# Heading
<script>
const foo = 1 + 1;
window.alert(`1 + 1 = ${foo}`);
</script>
Paragraphs of exposition.
People are saying that triple backtick fenced code blocks are used to preserve whitespace and fixed width, usually with syntax highlighting as a bonus. That's the expected behavior.
However with the described mermaid support, it's taking a fenced code block with a mermaid tag and transforming it into a graph.
When inspecting the text content of a markdown file, there's no difference between a `javascript` tagged code block, a `haskell` tagged one, and a `mermaid` tagged one. But now when rendering, the mermaid one is special cased.
This is undesirable for multiple reasons, the most obvious being that it's now harder to write a README that displays mermaid syntax.
A good starting point would be either different syntax or a different tagging convention. For instance I think I saw `!mermaid` suggested, where the `!` would mean that the code should be interpreted instead of rendered as code.
I don't have a horse in the race of what this looks like, only that there should be a distinction between rendered and interpreted code blocks.
If you explicitly want source code rendering don't add the mermaid tag to the block. There could be an argument that now you don't get syntax highlighting, but remember syntax highlighting itself is not part of any markdown spec and it differs wildly between implementations--there is no common grammar or spec for it even.
In all cases these are still valid markdown files and will pass through markdown processing, rendering, etc. systems without breaking them.
And yet Github's markdown support carries much more weight. Raising concerns at this point is a perfectly reasonable thing to do.
Why don't we just go back to xml and provide decent structured editors?
So, the question is would you rather have SVGs inline?
Personally I think the reference to another file is a perfectly fine compromise, as the content is sufficiently different to no longer be markdown.
Also, I personally hate markdown tables since editing even a single cell means that I likely have to then resize either the entire row or the entire column, or both. So when I do need tables I use HTML tables anyway.
At any rate, a middle-ground might be to have the diagram source as references at the end of the document, and reference those from the use site, like `![Chart][#chart]` or something. So you don't have to see the diagram source inline if you don't like it, but it's still there in the same file.
Another similar example, all of VSCode's configuration files are called filename.json but they aren't actually json (any spec compliant json parser would barf on them).
They could just have easily named them filename.jsonc (or whatever they actually are) but they didn't so we're stuck with all these .json files that json parsers won't actually parse and special hacks to validate them differently based on like if they're in a .vscode folder or if their name is some specific filename.
Unfortunately there's no way to wrangle millions of programmers so we're stuck with whatever bad decisions become popular.
IF that's not clear above, for example, trailing commas and comments are not allowed in JSON but they are in JSONC. You'd like your editor to highlight errors. Typically this is done by filename extension. .json = comments show as errors, .jsonc = comments OK. But VSCode named it's .jsonc files as .json so every editor that wants to be able to show if there are errors in your file now needs some random heuristic to decide how to interpret the file..... all because of a bad decision by 1 or 2 programmers that ended up being popular and now their too entrenched to fix it.
The same thing is true here. ``` is supposed to mark a codeblock as in show the text as is, whitespace as is, line breaks as is. If you want to write a tutorial on how to use mermaid in markdown you'd want ``` to show the mermaid source. Use some other tag for rendering. But now where stuck with an exception and more will be added.
And before you go say "there's no official spec", so what!? It's called being consistent and interpreting the contents of a ``` block is inconsistent.
```math
-b \pm \sqrt{b^2 - 4ac} \over {2a}
```
JavaScript ; poem ; ’90s email ; OP ; latex math ; ditaa
```!dot
(Markup)
```
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.
But lets reinvent the world in Js.. NIH is strong
Don't.
It's a sea shanty of XSS vulns.
The most recent one, https://security.snyk.io/vuln/SNYK-JS-MERMAID-2328372: I would be very concerned about trusting code that could be in any way adjacent to security written by whoever wrote (and whoever reviewed or committed) this original sanitizeUrl function <https://github.com/mermaid-js/mermaid/commit/066b7a0d0bda274...>. .replace(/javascript:/g, '') is obviously catastrophically wrong, breaking valid (though uncommon) URLs and completely failing to guard against javascript: URLs.
Yes, it’s fixed now, but the existence of the bug in the first place is highly alarming. No protection I can understand—for first-party use where you can trust the inputs it’s reasonable—but bad protection suggests someone tried but didn’t know what they were doing, and didn’t know that if you don’t know what you’re doing in security stuff you need to seek help, because there’s a surprisingly high chance that your bandaid will be worse than doing nothing (either that it actively makes things worse, or that it’s insufficient but gives an impression of safety). It’s dangerous cluelessness.
The middle one, https://security.snyk.io/vuln/SNYK-JS-MERMAID-1314738: the patch provided is utterly misguided and does not fix the alleged security vulnerability in the slightest—it barely even puts a bandaid over it, and it definitely breaks legitimate and reasonable stuff. See <https://github.com/mermaid-js/mermaid/pull/2123/commits/3d22...>: this is trivially insufficient and catastrophically wrong in its approach, so that if anything is actually depending on this code for security, it’s certainly broken. I haven’t immediately got an XSS in https://mermaid.live (something else is evidently providing the actual protection—so I think the advisory was either never valid, or it’s still unfixed), but it ruins reasonable labels like “Contrast with javascript: ahead-of-time compilation makes it faster” or “Do you strip javascript: URLs?” by removing the “javascript:” (eww!), but I can easily sneak a javascript: in there because of the sequential replacement done, with the likes of `java<iframescript:`. This is perhaps even more bogglingly incompetent than the /javascript:/g deletion. (Note that I’m using the word “incompetent” in its strict meaning, in no way as a slur. We all start out incompetent; but we need to develop enough of a feel for basically everything that we can identify situations where we’re not competent.) And even apart from all that, URL schemes are case-insensitive, as seen in data:text/html,<img%20src=x%20onerror=JavaScript:alert(1)>, so /javascript/ without the /i (case-insensitive) flag is insufficient anyway.
I’ve looked at two of them, might as well look at the third, https://security.snyk.io/vuln/SNYK-JS-MERMAID-174698. Oh wow. The first patch <https://github.com/mermaid-js/mermaid/commit/c33533082c598a0...> introduced /javascript:.*/g removal, which is both insufficient and excessive as already mostly discussed, implemented separately for flowchart and gantt (that’s a terrible idea that will consistently lead to divergent changes and missed places; this is library functionality that needs to be maintained in one place). Then the second patch <https://github.com/mermaid-js/mermaid/commit/f11d1a6fa1a5350...> switches to a real sanitiser, but leaves the terrible first approach around in a comment in one instance. And removes a bunch of console.log() calls that should never have been there. And starts escaping = as = for no reason (if you need this, something is badly wrong). And changes some conf to getConfig().flowchart for some reason. All in the one commit, with a very weak commit message that doesn’t address the why at all, and ignores most of the changes. This is not a clean code base or repository.
From what I’ve seen so far, I’m fairly confident that an audit of the code base would reveal multiple fairly severe security vulnerabilities. Also that if I started actually reviewing it I’d be crying out to drastically refactor large parts of it. I’m going to tip-toe away before I start poking this 20,000 line code base (excluding tests).
Someone can report that the second one hasn’t actually been fixed, and that the patch was actively harmful and worse than useless, if they’d like to. I don’t want to engage, lest I get sucked in. :-)
Was about to suggest this
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?
click NodeName “URL”
There was an outstanding feature request on their forum for quite some while so didn't hold my breath for this to be added but glad it has.
IMO, this was the missing piece for us when it came to keeping diagrams up to date.
[0] - https://docs.gitlab.com/ee/administration/integration/plantu...
https://www.npmjs.com/package/@hpcc-js/wasm
I even did it myself a few months ago :)
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?
Also, ER diagrams are nigh unreadable due to the unusual relationship visual style used.
I remember the docs for Mermaid.js talk about varying document trust levels, which is not something I want involved in a diagramming DSL.
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 :/
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).
Thanks for the tip of nomnoml, didn't know about it.
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/...
PS: thanks for investing so much work into Tsukihime!
edit: Oh, I'm on Linux btw.
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.
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.
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 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.
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 ;)
Also on Azure DevOps too https://docs.microsoft.com/en-us/azure/devops/project/wiki/w...
What a time to be alive! :-)
https://about.gitlab.com/releases/2017/12/22/gitlab-10-3-rel...
The real criticism of the original comment is that markdown has never really been "portable"; yes there's now a hard dependency (for some definition of "hard") on mermaidjs for GitHub-flavored-markdown, but that actually brings it in line with other implementations. So has portability been obviated or just slightly changed?
Also The Arte of ASCII RFC8140 https://datatracker.ietf.org/doc/html/rfc8140
I wrote a trivial webstack to answer 200 to the webhook and then everything works. (Don’t know if I can publish it unfortunately.)
(Condolences to those stuck on Bitbucket).
This is currently how I document my home servers
1. Visual code draw.io extenstion 2. Save diagram as FILENAME.drawio.svg 3. Link file in markdown
I'd have preferred PlantUML but Mermaid is a great start.
[1]: https://ivanceras.github.io/svgbob-editor/ [2]: https://textik.com
I would love to see it working in the Github Wiki too.
They should really unlock this issue[0] and let people know.
We tried to use it for flowcharts in our documentation and its layout wasn't right. I'm assuming it uses a force directed layout system.
We switched to creating diagrams in Excalidraw and everyone is happy.
Very happy that 1.5 years later they are again being rendered.
[1] https://github.com/Zettlr/Zettlr
[2] https://docs.zettlr.com/en/reference/markdown-basics/#zettlr...
So ASCII drawings could be rendered into pretty ones.
```mermaid
flowchart TD;
A[Depoy to production] --> B{Is it Friday?};
B -- Yes --> C[Do not deploy!];
B -- No --> D[Run deploy.sh to deploy!];
C --> E[Enjoy your weekend!];
D --> E[Enjoy your weekend!];
```
C --> E[Enjoy your weekend!];
D --> E[Have fun this weekend!]; C --> E;
D --> E;
E[Enjoy your weekend!];The top example there takes a GraphViz description and passes it into the dot command, placing the resultant SVG into the HTML output.
Another nice thing is that PlantUML is supported (alongside Mermaid) in GitLab, and has been supported for at least two years. You can embed PlantUML diagrams into your README without committing any images to the repo or linking to external images, just like Mermaid.[1]
[0] - https://plantuml.com/sequence-diagram
[1] - https://docs.gitlab.com/ee/administration/integration/plantu...
So I think I'd prefer ASCII art diagrams for this sort of thing. (In fact there was recently an ASCII diagram drawing tool on the HN front page, https://asciiflow.com/ )
Does anyone know if there is a decent tool similar to mermaid-cli allowing for command-line based generating PNG or SVG mermaid diagrams, but without having to install bazillion of NPM packages first?
I want to be able to point a method of a classDiagram at a decision chart with arrows then to the row of a database table.
This is the sort of thing I reach to either Graphiviz or for Omnigraffle currently, and this doesn't seem to solve.
With Mermaid each type of diagram is distinct and locked down to specific intended uses.
not github specific but i really enjoyed this quite long post/tutorial on realtime collaboration with mermaid (using notion)[2].
[1] https://github.com/github/roadmap/issues/372 https://news.ycombinator.com/item?id=29927962 (72 points, 14 comments, 31 days ago)
[2] https://www.happyandeffective.com/blog/realtime-collaborativ... https://news.ycombinator.com/item?id=30238208 (12 points, 2 comments, 7 days ago
I prefer ASCII drawing characters/boxes, similar to mentioned in this[1] and following comments.
I was poking around the examples and live editor, and it seemed impossible to do except with an image link, which is rather more cumbersome.
I've got all of my diagrams ripped out of lucidapp and into project repos, but the issue I'm having is that IntelliJ is still shipping a year+ outdated version of mermaid, which makes ordering nodes impossible in some cases.
I had hoped to use Mermaid in a static site generator to create SVG diagrams at build time (to avoid requiring JavaScript), and this dependency was irritating enough that I abandoned Mermaid entirely and instead compiled Graphviz to WebAssembly (and honestly I prefer Graphviz's syntax, although it doesn't support nearly as many diagram types as Mermaid).
The whole idea of depending on a full blown Chromium for your cli tool just to convert that mermaid description into an SVG or PNG seems bad to me. It was my personal turning point where I stopped using JavaScript based tools in my toolbox.
Still, since GitHub does render Mermaid, it might be useful to create a GitHub action that automatically generates an updated diagram.MD directly from the models on every commit.
I’m the main author of KeenWrite (see screenshots[1]), a type of desktop Markdown editor that supports diagrams. It’s encouraging to see that Mermaid diagrams are being supported in GitHub. There are a few drawbacks on the syntax and implications of using MermaidJS.
First, only browser-based SVG renderers can correctly parse Mermaid diagrams. I’ve tested Apache Batik, svgSalamander, resvg, rsvg-convert, svglib, CairoSVG, ConTeXt, and QtSVG. See issue 2485[2]. This implies that typesetting Mermaid diagrams is not currently possible. In effect, by including Mermaid diagrams, many documents will be restricted to web-based output, excluding the possibility of producing PDF documents based on GitHub markdown documents (for the foreseeable future).
Second, there are numerous text-to-diagram facilities available beyond Mermaid. The server at https://kroki.io/ supports Mermaid, PlantUML, Graphviz, byte fields, and many more. While including MermaidJS is a great step forward, supporting Kroki diagrams would allow a much greater variety. (Most diagrams produced in MermaidJS can also be crafted in Graphviz, albeit with less terse syntax.)
Third, see the CommonMark discussion thread[3] referring to a syntax for diagrams. It’s unfortunate that a standard “namespace” concept was not proposed.
Fourth, KeenWrite integrates Kroki. To do so, it uses a variation on the syntax:
``` diagram-mermaid
```
``` diagram-graphviz
```
``` diagram-plantuml
```
Fifth, if ever someone wants to invent a programming language named Mermaid (see MeLa), then it precludes the possibility of using the following de facto syntax highlighting:
``` mermaid
```
``` diagram-mermaid
```
``` mermaid
```
``` java
```
``` language-java
```
[1]: https://github.com/DaveJarvis/keenwrite/blob/master/docs/scr...
[2]: https://github.com/mermaid-js/mermaid/issues/2485
[3]: https://talk.commonmark.org/t/mermaid-generation-of-diagrams...
"Mermaid: a Javascript based diagramming and charting tool that uses Markdown-inspired text definitions and a renderer to create and modify complex diagrams."