221–230 of 272 posts
That is pretty complicated Just use 1. Visual code draw.io extenstion 2. Save diagram as FILENAME.drawio.svg 3. Link file in markdown
I'd have preferred PlantUML but Mermaid is a great start.
Earlier quoted context omitted.
We need to go back to something like Word documents. We’ve come full circle
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.
Earlier quoted context omitted.
Alright, but how do I embed highlighted Mermaid source code in Markdown now?
embed the HTML: your mermaid code with highlighted sections 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…
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.
Earlier quoted context omitted.
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 th…
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
```mermaid
flowchart TD;
A[Depoy to production] --> B{Is it Friday?};
B -- Yes --> C[Do not deploy!];
B -- No --> D[Run deploy.sh to deploy!];
C --> E[Enjoy your weekend!];
D --> E[Enjoy your weekend!];
```
C --> E[Enjoy your weekend!];
D --> E[Have fun this weekend!];Earlier quoted context omitted.
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.
Mermaid is as readable as C++. 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.
Still, since GitHub does render Mermaid, it might be useful to create a GitHub action that automatically generates an updated diagram.MD directly from the models on every commit.
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 annoyi…