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.)
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.
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
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.
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?
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.
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.
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
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)
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..
<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.
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.
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.
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:
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.
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.
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.
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.
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.
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.
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.
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.
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.
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).
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:
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]
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.
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.
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 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.
> 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.
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.
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.
> 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.
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.
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.
> 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.
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.
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 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.
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.
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.
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.
“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.
> 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:
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.
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.
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.
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.
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.
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.
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.
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.
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/ )
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.
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.
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.
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 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?
271 comments
[ 6.8 ms ] story [ 271 ms ] threadnot 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 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).
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?
One thought though, on the syntax. Wouldn’t it be a bit odd if suddenly this line in a README.md:
Rendered as: ? Isn’t that kind of what we’re doing here with the mermaid source tag? That tag is for showing source code, no? Feels like there should be another tag for rendering it.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.
https://github.github.com/gfm/#fenced-code-blocks
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):
```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.
[0] - https://docs.gitlab.com/ee/administration/integration/plantu...
http://viz-js.com/
https://www.npmjs.com/package/@hpcc-js/wasm
I even did it myself a few months ago :)
[0] - https://plantuml.com/object-diagram
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.
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...
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.
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.
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.
https://daringfireball.net/projects/markdown/
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.
Renders Not !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
is rendered, rather than it itself. And if we want the code itself, we have: ! 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?> 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
is deemed an improvement over, for example, Java Swing’s but in both cases, it’s the result that counts.> 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/martinthomson/aasvg
* 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.
https://runarberg.github.io/mathup/
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
https://daringfireball.net/projects/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.
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/ )
So ASCII drawings could be rendered into pretty ones.
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.
[1]: https://ivanceras.github.io/svgbob-editor/ [2]: https://textik.com
I would love to see it working in the Github Wiki too.
Don't.
It's a sea shanty of XSS vulns.
https://snyk.io/vuln/npm%3Amermaid
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 &...
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?