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.
“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")
}
}
is deemed an improvement over, for example, Java Swing’s
From your same link it does not say un-rendered readability was a secondary goal, it says the exact opposite:
> 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.
To be fair, I'm not sure "offline readability" is an actual problem anymore. VS Code and (presumably) other IDEs offer a very simple live-preview window for viewing and editing markdown files.
While it is true, these features seem to me to be added because Markdown is (ab)used the way it is. The issue is if you are working in an environment where it isn't possible, e.g. on a server where you only have vi/nano, and not even a TUI browser (or if you don't want to use an editor based on electron).
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.)
To you it does but manifestly your use case doesn’t matter to the people writing these pieces of software and these readme files. They care about their audience which want different things than you. At some point you can’t expect the world to cater for you. You have to deal with the annoyances which come with doing things differently or move on with your time.
* 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.
How so? Word Documents are not made to be edited by hand. They are meant to be edited in Word. Markdown even with Mermaid is still readable and editable by hand. While I can agree Mermaid isn't my ideal markup, there are alternatives and you can even propose your own.
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.
I agree that it is no ideal, at least for my tastes, but I think what you are stating is an exaggeration. If you are using reference points like someone that knows little to nothing about technology, then just about anything different that what they are used is probably as readable as C++. For example, trying to read HTML would be the same to my grandma as trying to read C++.
Readable by humans is relative. Mermaid does not make it unreadable to some humans. Again, you are free to create an alternative that makes it more readable. Some could say that adding tables to markdown makes it unreadable. There are lot of extensions for markdown that adds features, but you have to know what they are to read them and use them. Grandma doesn't have to use Mermaid if she doesn't want to.
Which specific github flavored features violate the original spirit of markdown? I only use the basic syntax, but I don’t think I’ve run across a readme edit that hasn’t adhered to that original spirit.
I don't think GP was suggesting that there's anything specific wrong with GFM, but more that the way github encourages READMEs to be used (by auto-rendering all READMEs to HTML) creates an abstraction that shadows the readable-as-text goals of markdown.
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.
> Markdown was meant to be rendered, not left as plaintext (for viewing, at least as a primary use-case). [...] meant to be a lightweight way […]
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.
But Mermaid code is much more readable in plaintext than a link to an image elsewhere?
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)
```
Renders
print(42)
Not
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
$$
is rendered, rather than it itself. And if we want the code itself, we have:
```tex
\code\here
```
! How do you give an example of Mermaid code in a Readme? I'm sure they've thought of it, it can be escaped, but why? Why is it different?
The purpose of the implementation of the language may be readability, but surely the purpose of the existence of the language is to be rendered not to perpetuate its own existence...
> Markdown’s syntax is intended for one purpose: to be used as a format for writing for the web. [1]
> 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).
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.
I think you're talking past each other a little. Markdown was designed to let you "write HTML using an easy-to-read, easy-to-write plain text format", and to "be publishable as-is, as plain text". Those are both explicitly stated design goals.
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.
It is still readable, though. It's not like there's a base 64 encoded blob in the middle. Mermaid is reasonably comprehensible (as reasonable as any other code block, at least) without any rendering.
“A text-to-HTML conversion tool” with the “overriding design goal” of “[making] it as readable as possible”.
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.
The "easy-to-read [...] plain text format" indicates to me that the idea was that markdown should be readable in plaintext form too. The ability to convert it to HTML is a different goal?
Maybe? My point, though, is that from day 1 it was meant to be rendered as HTML. So what Github does with it (rendering README.md files) is perfectly compatible with that original intent. Just like everyone who used md->html renderers for their blogs or whatever other content.
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.
> Maybe? My point, though, is that from day 1 it was meant to be rendered as HTML.
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.
Rendering has HTML isn't really the issue, imo. The question is rather how readable the source remains, when you foget to fold lines, insert too many images without alt texts, intersperse regular HTML, etc.
> Markdown was meant to be rendered, not left as plaintext
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.
> 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.
Markdown is based on a really old nerd convention of stylising plain text. Things like /italics/ and *bold* predate MD by great many years. I was using some of markdown’s semantics even in the 90s.
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.
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.
> ASCII charts are very hard to format; you'll really need tools or editor plugins for that.
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.
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.
One thing that might help is using ":set virtualedit=all". This makes all lines act as if there are unlimited spaces at the end of line. That means you can move anywhere on the screen by cursor or by clicking with your mouse, etc, and not have to worry about typing in all the padding yourself. Once you place a character at column N, it will insert spaces up to column N-1 then place the new character.
Not a great answer: if you use evil-mode for emacs (eg with doom-emacs or spacemacs) you get picture-mode which can make ascii art a bit easier, and artist-mode which gives you point-and-click (or move-and-press-enter) ascii art drawing.
> 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:
ASCII-art is generally difficult to write as denoted by the numerous tools that have been created to generate ASCII-art for markdown. ASCII-art is also much more difficult to edit after the fact.
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.
> 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."
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.
Shameless plug. I wrote a math authoring tool Mathup[1] with that purpose in mind. That you could author math really easily which would also be easy to read in plaintext. You could write things like 1+2 / 3+4 which you would be rendered as you would expect, or you could write your matrices like A = [a, b; c, d].
My main reason for writing it was for inclusion in markdown documents.
> Similarily there have been many tools that let you add so-called ASCII-art diagrams to Markdown documents.
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.
ASCIIFlow is less accessible than Mermaid though for folks that use screen readers. Mermaid can be read as is from the source, or be transformed into a readable format for screen readers, but ASCIIFlow has no such mechanism to translate it into a format that can be accessible.
I’ve had reasonable success with ditaa. If you use it in orgmode, then editing the source dumps you into artist-mode, emacs can display the image result, and you don’t need to rely on a special export process as you generate an image to be used like any other
We should not forget, that the "spirit of Markdown" is:
> 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).
You’re at least the third person to point to that paragraph while failing to acknowledge an important paragraph further into the 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.
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.
If I need something to look good as text without any rendering I write text (a .txt file). Even the most basic features of markdown (inline code, italics, etc) look pretty nasty without post rendering.
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.
I’ve actually been using an almost identical filter for GraphViz markup in my university papers for the last year, except I added a leading exclamation point to the language tag to distinguish between included source and included markup:
```!dot
(Markup)
```
I wish they’d adopted something like that instead - I have no idea how you’d include highlighted Mermaid source in a GH markdown file.
Agreed; this is an annoying inconsistency. If you want to embed and render a non-Markdown file in Markdown, there's already another, far better syntax for that which is more in-line with the spirit of Markdown's "just text" philosophy:
I think this is a false equivalence. The content of SVGs is non-semantic; to get from SVG code to Meaning one needs to do some sort of rendering and re-interpreting of the resulting image. Even if for some simple images that could be done in-brain, that is not usually the case. Whereas something like Mermaid is intended to be meaningful both as code and as rendered output, just like Markdown itself. Having that additional meaning inline can be very helpful to faster understanding of the content, which is not usually going to be the case for inline'd SVG.
I don't know if it's a false equivalence, because I've read (and certainly written) a fair number of mermaid diagrams which are extremely hard to understand without seeing the rendered content.
It's subjective, in my opinion. I might be fine with inline SVGs if they were "smaller", ie didn't have the doctype and root element and general XML verbosity on all nodes. PlantUML / Mermaid have a much more to-the-point syntax.
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.
Yes, it sucks. This is why we can't have nice things. Because a million different programmers always choose some random incompatible interpretation and then we're all stuck with it.
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.
If I could have one wish, I'd replace file extensions with a hash of the spec and have someone maintain a lookup table from spec hash -> extension for rendering
That prevents any possibility for progressive enhancement though as your old renderer won't know the hashes for new but still mostly compatible spec versions.
It feels like Markdown and Jupyter notebooks in on the path to merging, and markdown is like the dumbed (need a different word for this, simplicated (though that that word is cumbersome)) down yaml which is a simplicated xml.
Why don't we just go back to xml and provide decent structured editors?
Yaml is now worse than the thing it was designed to replace. Rather than solve the real problem (ungood editors), we prop up and extend a janky solution.
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)
<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.
> What you're asking for is an uncommon edgecase that's not what people want in 99% of circumstances
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.
I don't think github should (generally) render stuff in the browser (although I see that both "benign"[1] graphs and source code highlights, not to mention the somewhat simple translation from Markdown to html - probably could be done in the browser as js/wasm.
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..
You missed the point, that being; isn't triple backticks meant for whitespace preserving, highlighted in certain cases source code? And not embedding other file types.
No there's not a formal requirement or spec for how markdown blocks are rendered. Even things like syntax highlighting are optional choices different renderers make (and even the whole idea of highlighting is not specified or defined, how do you define the grammer, etc?).
Sure but there's no markdown spec. Markdown is purely a series of blog posts by John Gruber and a collection of different implementations. CommonMark is as close to as it's gotten to a formal spec, and even it says there is no requirement the info string (i.e. text like mermaid after backticks) be interpreted for specific rendering (or not rendering) of the content: https://spec.commonmark.org/0.28/#fenced-code-blocks
In practice most markdown renderers will strip HTML or at least script tags as it is obviously a cross site security risk to allow github.com to serve user uploaded scripts without sanitization.
I think you're caught up on exactly the opposite of the complaint here. People aren't requesting JS execution, they have the various "notebook" solutions for that.
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.
You're pushing a rock up hill--many markdown renderers natively support mermaid, plantUML, etc. using fenced 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.
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’m not impressed with what I see of the three that there are, in some cases to do with how they came about and in some how they’ve been fixed.
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. :-)
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?
Azure Devops wikis have excellent (although not full support) for mermaid diagrams. One power user feature I like is the ability to add a hyperlink to graph nodes like so:
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.
Other services, such as Gitlab[0], allow you to embed Graphviz & PlantUML into a README just like (and alongside) Mermaid, but the images are rendered server-side.
There are definitely some JS libraries for it that exist. I don’t know all the details but I often find myself Googling “graphviz online” and clicking the first link to quickly mock up diagrams. So in short, I’ve used it on the web before.
Having tried to think about how to map Graphviz (language parsing, styles, and layout) onto our graph drawing offering, I'm not sure I can agree here. The dot graph description language itself is fairly simple (-ish). There are a few nasties like the HTML record support, which can be annoying to support, but overall that part isn't so bad. When it comes to laying out the graphs and rendering anything Graphviz has so many unique features that it can be a lot more work.
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.
Not sure why, but none of these render anything for me. It gives the progress message, then I get a plain square with no content in it. I've tried Firefox with and without uBlock enabled, and Brave with "Shields" up and down.
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 ;)
There's no hard dependency at all. The markdown will parse just fine without mermaid.js, it basically just takes a code block and runs it through the mermaid.js code if it matches the language
I'm not talking about a dependency for the file to be readable. I'm talking about a dependency for the diagram to be useful. I'm not opposed to extending markdown, but most functionality like this seems to involve bolting on external dependencies to take advantage of it.
So you want every markdown parser to support building diagrams as well? That seems much more difficult than offloading it to an open source library. Why waste effort that already has gone into building an easy to read diagraming language?
I'm pretty sure stakkur means mermaidjs is a bad option for markdown, as its source form is not "useful" as a diagram, and that it's actually GitHub which is saying every "markdown parser (/renderer) should support building diagrams as well" since they're encouraging its use by supporting the syntax.
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?
There's also been other Markdown renderers that support this exact syntax for Mermaid blocks for ages. I have a site that's generated using mkdocs that uses Mermaid diagrams, and I was able to open up one of the files from that site in Github and view the diagrams.
The alternative is no diagram at all, which sucks for understanding, or linking to an image that's likely just a binary blob which is now a hard dependency on your markdown file too. Mermaid is a great fit, it's a text description of common graph types and it's meant to be read, written, and understood by humans in text form.
This can be done with Bitbucket but the existing marketplace plug-in has been broken since they added the connect/disconnect webhooks as mandatory. Of course, the plug-in is provided by bitbucket …so that’s fun.
I wrote a trivial webstack to answer 200 to the webhook and then everything works. (Don’t know if I can publish it unfortunately.)
Honestly, Friday deploys are the best deploys. You’re extra motivated to get things out, fewer people will be around to complain if things are going wrong (at least if you mostly make money in the week) and you want to go home so you’re motivated to just do it efficiently instead of hesitating. There is a risk of rolling bugs on the weekend but there’s also a risk of having to spend your Mondays fixing twice as many (on average) bugs from bad rolls as well as other issues that may have been discovered on the weekend. The best trick for deploying on Fridays is to not write bugs, write software that is easy to roll back, and/or spend your weekend away from any kind of mobile signal.
Mermaid has explicit support for diagrams that look UML-ish (never mind the filled triangle arrowheads for inheritance): class, state and sequence diagrams. Graphviz doesn't do that easily.
PlantUML[0], which is built on top of Graphviz, does have support for UML and other services such as Gitlab do support direct embedding of PlantUML (which also means you can embed Graphviz, since PlantUML is an extension of Graphviz).
We had a good number of diagrams in our readme.md files which worked fine on GitLab. And then we moved providers and GitHub wouldn't render then anymore.
Very happy that 1.5 years later they are again being rendered.
Zettlr[1] (FOSS) has mermaid support[2] included. Zettlr is a markdown editor for personal knowledge management and/or distraction free (scientific) writing w/ PDF publishing.
I love Mermaid! I used to use that bitch all the time in college to make beautiful flowcharts and my friends would always ask me how I made them so nice looking. Another awesome thing about Mermaid is since it’s grounded in the HTML/CSS/JS web stack you can easily modify certain things in diagrams to do any custom tricks you need for your specific diagram. Aka Mermaid is hackable and I love software that is designed to give you that freedom.
```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!];
```
What happens if the two declarations of E conflict? E.g.:
C --> E[Enjoy your weekend!];
D --> E[Have fun this weekend!];
I like this approach of using the tag associated with a code block to determine how to render the output. It's the same approach I take in my markdown-derived markup language: https://github.com/smasher164/mexdown.
The top example there takes a GraphViz description and passes it into the dot command, placing the resultant SVG into the HTML output.
sequencediagram.org is a pleasant (and free) tool for generating standalone diagrams like this outside of GitHub. I discovered it while helping Corrily with their docs, e.g. the diagram at the top of this page: https://docs.corrily.com/docs/price-optimization-overview
Something to know is that sequencediagram.org seems to be just a website skin around PlantUML Sequence Diagrams[0]. PlantUML is open source and is ultimately built on top of Graphviz as well.
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]
This is interesting, but I personally really like that markdown is almost as legible as plain text as when rendered, which things like this sort of break.
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/ )
I was recently evaluating Mermaid for one of my projects but I could not get mermaid-cli to work (one of 3rdparty npm libraries was broken) and I needed a way of automating graph creation.
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 really like diagrams as text for simple diagrams where you don't care too much about the formatting. I think Figma is better if you really care about the formatting. I just discovered this the other day, but you can create mermaid diagrams in Notion by adding a codeblocks and selecting the "mermaid" language from the dropdown.
I agree with your sentiment, although personally i like the mermaid syntax (as someone who's bad at drawing ASCII art). Are you aware of native implementations of the mermaid syntax which i could use part of my site pipeline to build SVGs/PNGs instead of rendering client-side with javascript?
Is there any mermaid specification syntax for directly embedding diagrams into a markdown file (like by flagging the start of the diagram with a special title like #### diagramtypename) ?
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 started using this when I saw the initial announcement that they were working on integration.
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.
This brings one of my favorite features from https://hackmd.io (a site that I still love for early collaboration). I still love hackmd for its "gists on steroids", though I wish it had included git hosting.
Yes, it uses browser APIs (e.g. SVGGraphicsElement.getBBox()) to measure text, compute transformations, etc.
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).
Yeah, I was wanted to use the Git graph feature to create some nice diagrams. I expected the cli to work just like graphviz. Yet I was greeted by a stacktrace from Chromium since it did not work in WSL.
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.
Neat! Hadn’t used Mermaid before today, and it was easy enough to pick up to do a same-day turnaround for a client-facing PR with an embedded flow diagram to support a needed discussion. I’ll be interested to see if/how visual diffs work out for this.
Fantastic idea - some rough edges in actual implementation though.
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:
The diagram- prefix tells KeenWrite that the content is a diagram. The prefix is necessary to allow using any diagram supported by a Kroki server without having to hard-code the supported diagram type within KeenWrite. Otherwise, there is no simple way to allow a user to mark up a code block with their own text style that may coincide with an existing diagram type name.
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
```
My feature request is to add support for Kroki and the diagram- prefix syntax. That is:
``` diagram-mermaid
```
And deprecate the following syntax:
``` mermaid
```
And, later, introduce the language- prefix for defining code blocks that highlight syntax. That is, further deprecate:
``` java
```
With the following:
``` language-java
```
That would provide a “namespace” of sorts to avoid naming conflicts in the future.
I used this for documentation in a project. Its kind work intensive to update and keep the diagrams, but the fact that you can't sync with the code in GitHub is a real plus.
this looks excellent! last time i needed something like this it was fairly time consuming to do it in tikz, something quick in markdown is an awesome idea!
I hope they support the full suite of mermaid diagrams, not just a small subset like they do in Azure DevOps. Which is quite frustrating. My team has to take pngs and keep the source code at the bottom of wiki pages.
"Mermaid: a Javascript based diagramming and charting tool that uses Markdown-inspired text definitions and a renderer to create and modify complex diagrams."
has anyone had success using mermaid diagrams for real-time collaboration? Seems you should be able to use this to draw pictures while chatting with someone, akin to a white-boarding experience.
mermaid is great. I used a mermaid plugin for my own markdown support - formatting took a bit of a hit so maybe this will prompt better native support.
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.