Get the top HN stories in your inbox every day.
avgcorrection
daptaq
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.
It should really be called RENDERME.
Someone
The first paragraph of https://daringfireball.net/projects/markdown/:
“Markdown is a text-to-HTML conversion tool for web writers. Markdown allows you to write using an easy-to-read, easy-to-write plain text format, then convert it to structurally valid XHTML (or HTML).”
⇒ I think “easy to read and write” is an important, but secondary goal. The goal is to render to (X)HTML.
That’s similar to how SwiftUI’s
struct ContentView: View {
var body: some View {
Text("Hello World")
}
}
JFrame frame = …
JLabel label = new JLabel("Hello World");
frame.getContentPane().add(label);
zamadatix
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.
undefined
julienb_sea
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.
_k9eq
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.
cerved
My vanilla vim on ssh begs to differ. Offline readability matters
darknavi
Assuming that those tools also implement the same set of MD functionality (like Mermaid)
laumars
Yes. The main use case I have for markdown is:
* 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.
armchairhacker
We need to go back to something like Word documents. We’ve come full circle
junon
Not everyone uses vscode
didericis
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.
anderspitman
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.
daptaq
My go-to example is uBlock: https://raw.githubusercontent.com/gorhill/uBlock/master/READ..., despite being a great add-on, has 1/3-1/2 of unlegible Markdown, that looks nice when rendered.
PinguTS
Markdown has always been about "renderme". From the beginning.
If you want a simple README, then do a README and not a README.md.
avgcorrection
> It should really be called RENDERME.
Hah—yes!
tomrod
I'm getting vibes of "MOISTURIZE ME" from Doctor Who.
spoils19
RENDERME, nice one!
glennvtx
README.HTML
berkes
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.
Steltek
> 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.
IggleSniggle
I do tables, but I will admit to having them auto-formatted on save. That is, I type a pipe separated list manually, and auto-space it on save.
raman162
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.
tasty_freeze
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.
raman162
This is cool, didn't know about that, will try that out next time.
dan-robertson
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.
throw0101a
> 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:
* 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:
actually_a_dog
I saw several things that looked promising on Github:
* 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.
jasonlotito
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.
avgcorrection
> 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.
runarberg
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.
rektide
> 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.
birdyrooster
the nub
moolcool
To that point, ASCIIFlow is an amazing tool which I use constantly when working on markdown files https://asciiflow.com/#/
enzanki_ars
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.
llimllib
I used it yesterday and really wished it supported dashed lines!
mafro
Nice tip! I use Monodraw which is macOS only
Steltek
Behaves like it's Chrome only? Gonna have to pass on that one.
Or maybe MacOS only? I dunno. Definitely doesn't feel snappy and certain things just don't work.
timwis
I’m super excited for this!
One thought though, on the syntax. Wouldn’t it be a bit odd if suddenly this line in a README.md:
```js
const foo = 1 + 1
```
`2`
alaroldai
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)
```
Ajedi32
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:
Arnavion
It's nice to have the diagram source in the same file that uses it, instead of a separate file that needs to be kept in sync.
dijit
Since it’s sufficiently different to how it’s rendered its really more like an SVG than a table.
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.
asiachick
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.
anchpop
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
account42
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.
mminer237
I agree. R Markdown has R code execution as part of it's Markdown flavor and it distinguishes code block vs code execution as ```R vs ```{R}
sitkack
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?
rch
Lack of high-quality free editors was a massive problem with xml, particularly when xsd was involved.
qbasic_forever
Only the mermaid identifier is supported for triple backticks blocks, you can't put js and have it spit out script that executes in the browser.
e12e
I think op meant that we can:
```ruby
# syntax highlighted as ruby
a = 1 + 1
```
```js
// syntax highlighted as js
a = 1 + 1
```
```!ruby
# evaluated
as ruby
a = 1 + 1
# renders 2 because of implicit return?
```martinwoodward
The idea of the bang syntax came up. https://talk.commonmark.org/t/mermaid-generation-of-diagrams...
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)
mukundesh
Would be good to copy from MkDocs Material
https://squidfunk.github.io/mkdocs-material/reference/code-b...
``` py hl_lines="2 3"
def bubble_sort(items):
for i in range(len(items)):
for j in range(len(items) - 1 - i):
if items[j] > items[j + 1]:
items[j], items[j + 1] = items[j + 1], items[j]
tehbeard
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.
qbasic_forever
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?).
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/
acchow
It's rendering style, not execution.
reificator
Which is the exact inconsistency under scrutiny here.
qbasic_forever
Markdown supports arbitrary HTML, you can do this:
# Heading
<script>
const foo = 1 + 1;
window.alert(`1 + 1 = ${foo}`);
</script>
Paragraphs of exposition.
dan-robertson
FWIW, you also sometimes see
```math
-b \pm \sqrt{b^2 - 4ac} \over {2a}
```
JavaScript ; poem ; ’90s email ; OP ; latex math ; ditaa
berkes
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.
¹https://joplinapp.org/ EDIT: I'm not affiliated to joplin in any way. Just love it.
wscott
https://obsidian.md/ can also render Mermaid diagrams
Ciph
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.
laurent123456
This is a known issue which hopefully should be fixed soon: https://github.com/laurent22/joplin/issues/6074
undefined
milofeynman
I use Joplin at home and want to use it for taking notes at work. I love it.
zmmmmm
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.
spacexsucks
Been using plantuml for ever in gitlab markdown.
But lets reinvent the world in Js.. NIH is strong
no-dr-onboard
Protip to anyone using Mermaid.js
Don't.
It's a sea shanty of XSS vulns.
gavingmiller
3 is hardly a sea shanty of vulnerabilities for a 7 year old library. I think you're conflating releases with vulns.
chrismorgan
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. :-)
undefined
the_gipsy
> I don’t want to engage, lest I get sucked in. :-)
Was about to suggest this
DiabloD3
This seems to be incorrect, the current version has no CVEs according to that tracker.
kuroguro
I think the parent comment is just saying that multiple vulns have been found recently. There's a good chance there's more.
AlfeG
Not sure if this is bad? Should we abandon any lib that has cve?
undefined
Someone1234
Does this mean it is bad or simply popular? Unpopular/untested libraries rarely have previously found XSS vulnerabilities for example.
billconan
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?
undefined
undefined
eminence32
Gitlab supports mermaid too. It's always nice when there's feature parity between the two, as it makes it easier to jump between them.
this_steve_j
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:
click NodeName “URL”
wjdp
Been using it in Gitlab for a while, was rather surprised Github didn't support it when I pushed a repo there.
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.
luxurytent
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.
creakingstairs
That is such a great idea. Thank you for sharing that.
jonpalmisc
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.
nanomonkey
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.
djur
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.
eurasiantiger
No data flow diagrams though, and that is a really big omission which other diagrams don’t cover well.
WalterGR
Has Graphviz been re-implemented in JavaScript or compiled to WASM?
schemescape
Yes, several times:
https://www.npmjs.com/package/@hpcc-js/wasm
I even did it myself a few months ago :)
lelandbatey
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.
[0] - https://docs.gitlab.com/ee/administration/integration/plantu...
jonpalmisc
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.
donatj
It's a simple well documented language. Righting a fully functional JS Graphviz parser from scratch would take a couple days at most.
ygra
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.
WalterGR
The parser is only the beginning. Table stakes. For example: GraphViz has 8 layout engines. Which of those need to be implemented in JS?
undefined
jopsen
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?
eurasiantiger
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.
lpghatguy
This is a problem I've always had with Mermaid too. Custom theming is a no-go; it's easier to make attractive diagrams with GraphViz.
I remember the docs for Mermaid.js talk about varying document trust levels, which is not something I want involved in a diagramming DSL.
mafro
I use Monodraw on macOS and then embed the ASCII art into the Markdown in my README.
For example, https://github.com/mafrosis/step-ca-on-rpi#sso-for-ssh
I'd usually commit the source .monodraw files to the repo, but for some reason I didn't in that example repo :/
ak217
Mermaid is fantastic. Aside from mermaid, I've recently been introduced to nomnoml (https://nomnoml.com/) and it is fantastic as well.
My wish is for Mermaid and nomnoml to become universally supported among Markdown web renderers (I'm looking first and foremost at Github of course).
KaoruAoiShiho
I'm using mermaid to render this route map for interactive fiction: https://fiction.live/tsukihime/Satsuki-Yumizuka-Route/4B9obc...
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/...
thuringia
I don’t know about nomnoml but dot/graphviz works very well for this type of chart. Definitely another idea to try out.
PS: thanks for investing so much work into Tsukihime!
sundarurfriend
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.
edit: Oh, I'm on Linux btw.
Ciph
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.
mongol
Mermaid looks similar to PlantUML. Anyone that gave used both and can compare?
pizza234
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.
majkinetor
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.
Ciph
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.
Get the top HN stories in your inbox every day.
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.