Hacker News Reader

Comment by gepeto42 | Hacker News Reader

Mermaid is great for keeping simple diagrams in Markdown documents, and GitHub very recently started supporting it. Beats taking screenshots and uploading PNGs to the repo for sure!

For those using VS Code, this GitHub Markdown extension also renders mermaid: https://marketplace.visualstudio.com/items?itemName=bierner....

View on HN

But bizarrely they chose to execute and render it from code blocks, rather than syntax-highlight it like it's an example, and use some other syntax for rendering.

For example, Latex-style formulae are usually written (for markdown renderers that support it, not GitHub) $inline$ or in $$-delimited blocks. But if you want to explain how to do that then you write `$inline$` or

    ```latex
    $$
    \foobar
    $$
    ```

And that formats it, it doesn't execute the 'latex' (or whatever) interpreter with the contents and render its output.

Notion also renders Mermaid code blocks inline which I've found really helpful.

Wow! You're right. That's amazing. Definitely going to start using this.

Why not draw.io/diagrams.net? That used SVG which it embeds in pngs so they always render faithfully, and can be edited online, in the desktop app or directly in VS Code via a plugin.

That has dramatically better support.

Because you can't create PRs against it with readable diffs or code-generate them etc?

Exactly (though a diagramming tool could implement PRs in the future)

What might be cool is a graphical editor that uses Mermaid as a file format.

Trying to create certain types of diagrams (e.g. sequence diagrams) in Draw.io is a huge PITA.

Unfortunately, GitHub doesn’t support it in their built-in pages Jekyll implementation.

True, but the workaround is to render the Mermaid in the browser.

See: https://news.ycombinator.com/item?id=31275371

I try to keep html and javascript out of the markdown as part of the whole point is to not make writers know that stuff. Many of the authors I work with aren’t web devs so I don’t want to ask them to copy and paste special code beyond what mermaid requires.

Instead I just use GitLab where it works great. This is just an example of GitHub being a bit behind but am hopeful that they’ll eventually come up to speed. Especially since they have it in their markdown preview.

Yes! If you're making a product for "pure" writers, I'm with you almost 100%.

That being said, Markdown has always included the ability to insert custom HTML, because Gruber wrote it to scratch his own itch. He didn't make Markdown to hide HTML from himself, he made it to do away with all the ceremony of angle brackets, which are a PITA to type and definitely make the result harder to read from source.

From a readability standpoint, I'd prefer:

  ```mermaid
    stateDiagram
      [*] --> start
      start --> zero : 0
      start --> one : 1
      one --> one : 0, 1
      zero --> [*]
      one --> [*]
  ```

to:

  <div class="mermaid">
    stateDiagram
      [*] --> start
      start --> zero : 0
      start --> one : 1
      one --> one : 0, 1
      zero --> [*]
      one --> [*]
  </div>

But I can deal with that. What discomforts me personally is the worry that something about the mermaid.js implementation will break in a future browser version.

Were I compiling to SVG or PNG as part of my build tooling, I would have a lot more trust that I could maintain a working toolchain in the future.

JM2C, YMMV, &c.

It's also supported in Azure Devops wikis

Reply on news.ycombinator.com