[HN Gopher] Include diagrams in your Markdown files with Mermaid
___________________________________________________________________
Include diagrams in your Markdown files with Mermaid
Author : todsacerdoti
Score : 514 points
Date : 2022-02-14 16:58 UTC (6 hours ago)
(HTM) web link (github.blog)
(TXT) w3m dump (github.blog)
| mappu wrote:
| Gitea has had this feature for a while, it's really excellent.
| kderbyma wrote:
| mermaid is great. I used a mermaid plugin for my own markdown
| support - formatting took a bit of a hit so maybe this will
| prompt better native support.
| msdrigg wrote:
| Cool, now do latex
| martinwoodward wrote:
| Talking about it - https://talk.commonmark.org/t/math-
| rendering-re-visited/4086
| eminence32 wrote:
| 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 wrote:
| 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"
| Someone wrote:
| I like markdown, and can see the lure of additions such as this
| one, but I also sometimes wonder whether we gained much compared
| to _troff_ and its companion programs ( _pic_ , _eqn_ , _tbl_ ,
| _chem_ , etc. See https://www.troff.org/prog.html).
|
| If we added Unicode support and _html_ and _pdf_ output to those,
| I think the main thing we would miss is readability of the raw
| text. That doesn't look like much progress in half a century.
| tannhaeuser wrote:
| > _That doesn't look like much progress in half a century._
|
| Considering the author of groff became _the_ SGML expert, with
| SGML supporting custom syntax parsing ranging from troff-like
| line commands all the way to markdown or Wikimedia syntax or
| subsets thereof precisely for unifying ad-hoc syntax, and SGML
| the basis for the HTML vocabulary from which these want to run
| away, I 'd rather say tech is re-invented in generational
| circles. Or devs simply like to grow mini languages ;)
| [deleted]
| tombert wrote:
| I'm surprised I've never heard of this...there appears to be a
| pandoc filter readily available for this. This will be useful...
| medv wrote:
| Ansi draw tool what can parse boxes and move them?
| timwis wrote:
| 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 ```
|
| 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.
| mminer237 wrote:
| 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}
| asiachick wrote:
| 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.
| qbasic_forever wrote:
| 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.
| acchow wrote:
| It's rendering style, not execution.
| tehbeard wrote:
| 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 wrote:
| 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/bl
| ob/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/
| dijit wrote:
| There is a formal spec (from github themselves) for how
| it's rendered.
|
| What's debatable is what the spec does with the "info"
| section.
|
| https://github.github.com/gfm/#fenced-code-blocks
| qbasic_forever wrote:
| 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
| e12e wrote:
| I think op meant that we can: ```ruby
| # syntax highlighted as ruby a = 1 + 1 ```
|
| And: ```js // syntax highlighted as
| js a = 1 + 1 ```
|
| So maybe we should have something like a "bang" prefix to
| _evaluate and inline /embed_ like: ```!ruby
| # evaluated as ruby a = 1 + 1 # renders 2
| because of implicit return? ```
| martinwoodward wrote:
| 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)
| mintplant wrote:
| Alright, but how do I embed highlighted Mermaid source
| code in Markdown now?
| e12e wrote:
| 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..
| reificator wrote:
| Which is the exact inconsistency under scrutiny here.
| qbasic_forever wrote:
| Markdown supports arbitrary HTML, you can do this:
| # Heading <script> const foo = 1 + 1;
| window.alert(`1 + 1 = ${foo}`); </script>
| Paragraphs of exposition.
|
| 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.
| reificator wrote:
| 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.
| qbasic_forever wrote:
| 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.
| reificator wrote:
| > _You 're pushing a rock up hill--many markdown
| renderers natively support mermaid, plantUML, etc. using
| fenced code blocks._
|
| And yet Github's markdown support carries much more
| weight. Raising concerns at this point is a perfectly
| reasonable thing to do.
| Ajedi32 wrote:
| 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 wrote:
| 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 wrote:
| 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.
| brainfish wrote:
| 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.
| dijit wrote:
| 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.
| Arnavion wrote:
| 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.
| 0xbadcafebee wrote:
| Do they support a markdown Table of Contents yet?
| infensus wrote:
| Not as a syntax, but headings are parsed and there's a TOC
| dropdown to the left of the filename
| no-dr-onboard wrote:
| Protip to anyone using Mermaid.js
|
| Don't.
|
| It's a sea shanty of XSS vulns.
|
| https://snyk.io/vuln/npm%3Amermaid
| [deleted]
| DiabloD3 wrote:
| This seems to be incorrect, the current version has no CVEs
| according to that tracker.
| kuroguro wrote:
| I think the parent comment is just saying that multiple vulns
| have been found recently. There's a good chance there's more.
| AlfeG wrote:
| Not sure if this is bad? Should we abandon any lib that has
| cve?
| billconan wrote:
| 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?
| Someone1234 wrote:
| Does this mean it is bad or simply popular? Unpopular/untested
| libraries rarely have previously found XSS vulnerabilities for
| example.
| gavingmiller wrote:
| 3 is hardly a sea shanty of vulnerabilities for a 7 year old
| library. I think you're conflating releases with vulns.
| mafro wrote:
| 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 :/
| sandreas wrote:
| I like svgbob[1] and textik[2]. Far from perfect, but pretty good
| already.
|
| [1]: https://ivanceras.github.io/svgbob-editor/ [2]:
| https://textik.com
| HNSucksAss wrote:
| jonpalmisc wrote:
| 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.
| WalterGR wrote:
| Has Graphviz been re-implemented in JavaScript or compiled to
| WASM?
| schemescape wrote:
| Yes, several times:
|
| http://viz-js.com/
|
| https://www.npmjs.com/package/@hpcc-js/wasm
|
| I even did it myself a few months ago :)
| donatj wrote:
| It's a simple well documented language. Righting a fully
| functional JS Graphviz parser from scratch would take a
| couple days at most.
| WalterGR wrote:
| The parser is only the beginning. Table stakes. For
| example: GraphViz has 8 layout engines. Which of those need
| to be implemented in JS?
| ygra wrote:
| 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.
| [deleted]
| lelandbatey wrote:
| 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/p
| lantu...
| jonpalmisc wrote:
| 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.
| djur wrote:
| 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 wrote:
| No data flow diagrams though, and that is a really big
| omission which other diagrams don't cover well.
| nanomonkey wrote:
| 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.
| floodle wrote:
| I'm curious why they went for mermaid rather then GraphViz. Can
| anybody comment?
| limmeau wrote:
| 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.
| lelandbatey wrote:
| 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).
|
| [0] - https://plantuml.com/object-diagram
| smasher164 wrote:
| I like this approach of using the tag associated with a code
| block to determine how to render the output. It's the same
| approach I take in my markdown-derived markup language:
| https://github.com/smasher164/mexdown.
|
| The top example there takes a GraphViz description and passes it
| into the dot command, placing the resultant SVG into the HTML
| output.
| thrower123 wrote:
| Huh, they must have taken the integration they've had for a
| couple years now on the Azure Devops wikis and shifted it over to
| the GitHub side.
| ktzar wrote:
| 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.
| dima55 wrote:
| org-mode and org-babel already do this
| kaycebasques wrote:
| 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
| lelandbatey wrote:
| 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]
|
| [0] - https://plantuml.com/sequence-diagram
|
| [1] -
| https://docs.gitlab.com/ee/administration/integration/plantu...
| chrisweekly wrote:
| If you start getting into this kind of thing, you'll want to take
| a look at https://kroki.io which supports Mermaid along with lots
| of other diagramming formats.
| perth wrote:
| I love Mermaid! I used to use that bitch all the time in college
| to make beautiful flowcharts and my friends would always ask me
| how I made them so nice looking. Another awesome thing about
| Mermaid is since it's grounded in the HTML/CSS/JS web stack you
| can easily modify certain things in diagrams to do any custom
| tricks you need for your specific diagram. Aka Mermaid is
| hackable and I love software that is designed to give you that
| freedom.
| thangalin wrote:
| Re: https://github.com/github/markup/issues/533
|
| I'm the main author of KeenWrite (see screenshots[1]), a type of
| desktop Markdown editor that supports diagrams. It's encouraging
| to see that Mermaid diagrams are being supported in GitHub. There
| are a few drawbacks on the syntax and implications of using
| MermaidJS.
|
| First, only browser-based SVG renderers can correctly parse
| Mermaid diagrams. I've tested Apache Batik, svgSalamander, resvg,
| rsvg-convert, svglib, CairoSVG, ConTeXt, and QtSVG. See issue
| 2485[2]. This implies that typesetting Mermaid diagrams is not
| currently possible. In effect, by including Mermaid diagrams,
| many documents will be restricted to web-based output, excluding
| the possibility of producing PDF documents based on GitHub
| markdown documents (for the foreseeable future).
|
| Second, there are numerous text-to-diagram facilities available
| beyond Mermaid. The server at https://kroki.io/ supports Mermaid,
| PlantUML, Graphviz, byte fields, and many more. While including
| MermaidJS is a great step forward, supporting Kroki diagrams
| would allow a much greater variety. (Most diagrams produced in
| MermaidJS can also be crafted in Graphviz, albeit with less terse
| syntax.)
|
| Third, see the CommonMark discussion thread[3] referring to a
| syntax for diagrams. It's unfortunate that a standard "namespace"
| concept was not proposed.
|
| Fourth, KeenWrite integrates Kroki. To do so, it uses a variation
| on the syntax: ``` diagram-mermaid ```
| ``` diagram-graphviz ``` ``` diagram-
| plantuml ```
|
| The diagram- prefix tells KeenWrite that the content is a
| diagram. The prefix is necessary to allow using any diagram
| supported by a Kroki server without having to hard-code the
| supported diagram type within KeenWrite. Otherwise, there is no
| simple way to allow a user to mark up a code block with their own
| text style that may coincide with an existing diagram type name.
|
| Fifth, if ever someone wants to invent a programming language
| named Mermaid (see MeLa), then it precludes the possibility of
| using the following de facto syntax highlighting:
| ``` mermaid ```
|
| My feature request is to add support for Kroki and the diagram-
| prefix syntax. That is: ``` diagram-mermaid
| ```
|
| And deprecate the following syntax: ``` mermaid
| ```
|
| And, later, introduce the language- prefix for defining code
| blocks that highlight syntax. That is, further deprecate:
| ``` java ```
|
| With the following: ``` language-java
| ```
|
| That would provide a "namespace" of sorts to avoid naming
| conflicts in the future.
|
| [1]:
| https://github.com/DaveJarvis/keenwrite/blob/master/docs/scr...
|
| [2]: https://github.com/mermaid-js/mermaid/issues/2485
|
| [3]: https://talk.commonmark.org/t/mermaid-generation-of-
| diagrams...
| stakkur wrote:
| Thereby creating a hard dependency for your markdown files,
| obviating their portability.
| animal_spirits wrote:
| 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
| stakkur wrote:
| 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.
| djur wrote:
| 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.
| qbasic_forever wrote:
| 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.
| ghostoftiber wrote:
| 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.
| zellyn wrote:
| Like pikchr.org? I love it. Now I have to see if I can get
| pikchr support added to Mermaid, and we'll be off to the races!
| sidharthv wrote:
| Would you be willing to file a feature request in
| https://github.com/mermaid-js/mermaid-live-editor/issues ?
|
| 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.
| urashidmalik wrote:
| That is pretty complicated Just use
|
| 1. Visual code draw.io extenstion 2. Save diagram as
| FILENAME.drawio.svg 3. Link file in markdown
| zmmmmm wrote:
| 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.
| j0yb0y wrote:
| 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.)
|
| (Condolences to those stuck on Bitbucket).
| tjk_ wrote:
| Mind if I ask if you're having this issue on Bitbucket Cloud
| (bitbucket.org) or Bitbucket Server (self-hosted)?
| [deleted]
| MrTortoise wrote:
| I love how people keep discovering mermaid because i remember
| when i did many many years ago and it still brings me happiness
| today.
| donatj wrote:
| With Mermaid, the usage seems very locked down to a handful of
| use cases.
|
| I want to be able to point a method of a classDiagram at a
| decision chart with arrows then to the row of a database table.
|
| This is the sort of thing I reach to either Graphiviz or for
| Omnigraffle currently, and this doesn't seem to solve.
|
| With Mermaid each type of diagram is distinct and locked down to
| specific intended uses.
| boomskats wrote:
| Well this only took a few years! So happy to finally see it in.
|
| They should really unlock this issue[0] and let people know.
|
| [0] https://github.com/github/markup/issues/533
| emj wrote:
| IETF RFCs has some nice diagrams in ASCII
| https://datatracker.ietf.org/doc/html/rfc5905
|
| Also The Arte of ASCII RFC8140
| https://datatracker.ietf.org/doc/html/rfc8140
| ak217 wrote:
| 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).
| Ciph wrote:
| 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.
| KaoruAoiShiho wrote:
| 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 wrote:
| 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!
| bumblebeast wrote:
| It would be nice to have this tool: http://ditaa.sourceforge.net/
|
| So ASCII drawings could be rendered into pretty ones.
| mongol wrote:
| Mermaid looks similar to PlantUML. Anyone that gave used both and
| can compare?
| pizza234 wrote:
| 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 wrote:
| 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 wrote:
| 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.
| w4rh4wk5 wrote:
| Semi-related question: does mermaid-cli still bring along
| chromium to 'render' images?
| donio wrote:
| I just tried to install it and yes, it looks like mmdc still
| requires puppeteer and chromium. Which seems a bit ridiculous
| for a CLI tool.
| schemescape wrote:
| Yes, it uses browser APIs (e.g. SVGGraphicsElement.getBBox())
| to measure text, compute transformations, etc.
|
| I had hoped to use Mermaid in a static site generator to create
| SVG diagrams at build time (to avoid requiring JavaScript), and
| this dependency was irritating enough that I abandoned Mermaid
| entirely and instead compiled Graphviz to WebAssembly (and
| honestly I prefer Graphviz's syntax, although it doesn't
| support nearly as many diagram types as Mermaid).
| w4rh4wk5 wrote:
| Yeah, I was wanted to use the Git graph feature to create
| some nice diagrams. I expected the cli to work just like
| graphviz. Yet I was greeted by a stacktrace from Chromium
| since it did not work in WSL.
|
| The whole idea of depending on a full blown Chromium for your
| cli tool just to convert that mermaid description into an SVG
| or PNG seems bad to me. It was my personal turning point
| where I stopped using JavaScript based tools in my toolbox.
| avgcorrection wrote:
| 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.
| rektide wrote:
| > _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 wrote:
| the nub
| yu-carm-kror wrote:
| 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.
| OJFord wrote:
| I strongly disagree with that, they're about as clear and
| unintrusive as I can imagine, what else would you do?
|
| Personally _I_ even sometimes use them when markdown isn't
| available, as in won't be rendered.
| raman162 wrote:
| 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 wrote:
| 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.
| corysama wrote:
| http://casual-effects.com/markdeep/ has had ASCII-art-as-
| vector-image features for quite some time now. It's in need of
| a good editor, though.
| berkes wrote:
| 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 wrote:
| > 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.
| moolcool wrote:
| To that point, ASCIIFlow is an amazing tool which I use
| constantly when working on markdown files
| https://asciiflow.com/#/
| enzanki_ars wrote:
| 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 wrote:
| I used it yesterday and really wished it supported dashed
| lines!
| mafro wrote:
| Nice tip! I use Monodraw which is macOS only
| Steltek wrote:
| 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.
| daptaq wrote:
| 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.
| avgcorrection wrote:
| > It should really be called RENDERME.
|
| Hah--yes!
| spoils19 wrote:
| RENDERME, nice one!
| julienb_sea wrote:
| 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.
| darknavi wrote:
| Assuming that those tools also implement the same set of MD
| functionality (like Mermaid)
| armchairhacker wrote:
| We need to go back to something like Word documents. We've
| come full circle
| daptaq wrote:
| 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.
| tomrod wrote:
| I'm getting vibes of "MOISTURIZE ME" from Doctor Who.
| didericis wrote:
| 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 wrote:
| 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.
| Jtsummers wrote:
| > 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 mark _up_
| 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.
| avgcorrection wrote:
| > 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.
|
| https://daringfireball.net/projects/markdown/
| OJFord wrote:
| 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?
| Jtsummers wrote:
| > 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.
| daptaq wrote:
| 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?
| Jtsummers wrote:
| 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.
| daptaq wrote:
| 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.
| chipotle_coyote wrote:
| 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.
| Jtsummers wrote:
| 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.
| avgcorrection wrote:
| "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.
|
| I hope this clears things up.
| daptaq wrote:
| My go-to example is uBlock: https://raw.githubusercontent.c
| om/gorhill/uBlock/master/READ..., despite being a great
| add-on, has 1/3-1/2 of unlegible Markdown, that looks nice
| when rendered.
| glennvtx wrote:
| README.HTML
| runarberg wrote:
| 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.
|
| https://runarberg.github.io/mathup/
| prpl wrote:
| There is also https://github.com/asciitosvg/asciitosvg
|
| Used in zeromq docs.
| jasonlotito wrote:
| 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.
| throw0101a wrote:
| > _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:
|
| * https://github.com/martinthomson/aasvg
| actually_a_dog wrote:
| 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.
| p20z wrote:
| 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.
| innolitics wrote:
| I really like diagrams as text for simple diagrams where you
| don't care too much about the formatting. I think Figma is better
| if you really care about the formatting. I just discovered this
| the other day, but you can create mermaid diagrams in Notion by
| adding a codeblocks and selecting the "mermaid" language from the
| dropdown.
| victor106 wrote:
| For those interested in this I highly recommend the book
| mentioned in the blog post "The Official Guide to Mermaid.js"
| [deleted]
| a-dub wrote:
| this looks excellent! last time i needed something like this it
| was fairly time consuming to do it in tikz, something quick in
| markdown is an awesome idea!
| citizenkeen wrote:
| Just so we're clear, if I deploy to production on a Monday, I get
| to start enjoying my weekend?
| kilovoltaire wrote:
| 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/ )
| riffic wrote:
| if you use Obsidian, Mermaid is supported natively.
| plett wrote:
| It works in Joplin too
| jopsen wrote:
| 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?
| lpghatguy wrote:
| 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.
| eurasiantiger wrote:
| 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.
| rektide wrote:
| nicely seen[1] on their roadmap a month ago.
|
| not github specific but i really enjoyed this quite long
| post/tutorial on realtime collaboration with mermaid (using
| notion)[2].
|
| [1] https://github.com/github/roadmap/issues/372
| https://news.ycombinator.com/item?id=29927962 (72 points, 14
| comments, 31 days ago)
|
| [2] https://www.happyandeffective.com/blog/realtime-
| collaborativ... https://news.ycombinator.com/item?id=30238208 (12
| points, 2 comments, 7 days ago
| berkes wrote:
| Joplin, the Open source note-taking app1, 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.
|
| 1https://joplinapp.org/ EDIT: I'm not affiliated to joplin in any
| way. Just love it.
| [deleted]
| Ciph wrote:
| 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 wrote:
| This is a known issue which hopefully should be fixed soon:
| https://github.com/laurent22/joplin/issues/6074
| aseattledev1234 wrote:
| This is great, I have used mermaid for years and glad to see
| GitHub adding support.
| blackdogie wrote:
| This is a nice addition.
|
| I would love to see it working in the Github Wiki too.
___________________________________________________________________
(page generated 2022-02-14 23:00 UTC)