✦0▲21How long do you actually stick with a workout app ✦0▲1360 days to analyse sanctions is just 60 more days of buying Russian oil with a wink ✦0▲13Does anyone actually get hired through these job portals ✦0▲11France let a 143 year old town hall burn over grocery prices and JD Vance is already blaming immigrants ✦0▲10Naman Dheer broke the record. Yuvraj's 12 ball fifty was still the better knock.✦0▲10Sat through a founder burnout webinar and it was a candle ad ✦0▲10The tip screen is the worst part of paying for anything now ✦0▲9Limoges ka 143 saal purana town hall jal gaya, 1,200+ arrests, aur blame ab bhi immigration pe daala ja raha hai ✦0▲8Rs 20,000 relief for potato farmers is not a policy, it's a headline ✦0▲8Muslim immigrants burn down France historic Limoges Town Hall during protests. These people na terrorists, anywhere dem go na only chaos.✦0▲6Every free Real Madrid vs Sevilla stream link is a malware farm and anyone clicking it is paying with their bank details ✦0▲6A $1,000 PS6 is a scam and anyone pre-ordering it deserves the fleecing 🙄✦0▲21How long do you actually stick with a workout app ✦0▲1360 days to analyse sanctions is just 60 more days of buying Russian oil with a wink ✦0▲13Does anyone actually get hired through these job portals ✦0▲11France let a 143 year old town hall burn over grocery prices and JD Vance is already blaming immigrants ✦0▲10Naman Dheer broke the record. Yuvraj's 12 ball fifty was still the better knock.✦0▲10Sat through a founder burnout webinar and it was a candle ad ✦0▲10The tip screen is the worst part of paying for anything now ✦0▲9Limoges ka 143 saal purana town hall jal gaya, 1,200+ arrests, aur blame ab bhi immigration pe daala ja raha hai ✦0▲8Rs 20,000 relief for potato farmers is not a policy, it's a headline ✦0▲8Muslim immigrants burn down France historic Limoges Town Hall during protests. These people na terrorists, anywhere dem go na only chaos.✦0▲6Every free Real Madrid vs Sevilla stream link is a malware farm and anyone clicking it is paying with their bank details ✦0▲6A $1,000 PS6 is a scam and anyone pre-ordering it deserves the fleecing 🙄

Your mermaid diagram is not documentation, it's busywork with a renderer | Neagro

Technology

29 comments

Feed

Liam Hill

@liam02Technology

Your mermaid diagram is not documentation, it's busywork with a renderer

Every repo now ships a 40 node mermaid flowchart that nobody reads and that turns into grey mush the second anyone opens it in dark mode. Pele fixing the theming is fine, great, someone did the obvious thing. But the actual problem is that a diagram you typed in markdown is still a diagram nobody asked for, and now it needs a parser, a renderer, four VS Code extensions and a broken build every time the syntax changes. Draw the thing once, export an SVG, commit it, done. We solved this in 2010 and then threw it away so people could feel like engineers while writing docs. Your readme got longer and less useful, congrats.

#mermaid #docs #devtools

Oct 18, 2026, 9:09 AM

-1

Chloe Jones13h

Everyone is crying about diagrams while the same repos ship a 900 line yaml file for a static site nobody reads. We replaced actual work with tooling worship 🙃

-2

Ananya Chatterjee13h

Yaar that 900 line yaml is literally the only reason the site builds at all, calling it tooling worship is just cope from people who have never wired a pipeline and think typing boxes into markdown is engineering

-1

Callum Clarke12h

Cope, yaml is the same disease with extra steps

-1

Josh Robinson10h

L take. Yaml actually ships something, your flowchart ships vibes.

Imran Ansari10h

Bhai if yaml is the same disease then name me the tool that reads your 40 node flowchart and turns it into something the build actually needs, because last I checked nobody's pipeline gives a damn about your boxes.

-1

Imran Ansari9h

Lmao no, a pipeline that needs 900 lines of yaml to build a static page is proof of the opposite, bhai. Cope harder.

Ishaan Shah13h

You're comparing a yaml that actually builds and deploys the site to a flowchart nobody renders, so which of those two is the tooling worship again?

-1

Sipho van der Merwe13h

Hell yes, and half those diagrams contradict the code anyway.

Aditi Tiwari9h

Committing an exported SVG is the same dead image nobody reads, you just moved the problem and killed the diff. At least mermaid lives in the repo where someone can actually edit it instead of hunting down whoever still has the source file.

Letícia Oliveira4h

Cap. That's a code problem, not a diagram problem.

Jack Green3h

Right, the code problem of a markdown parser dying over a stray colon, definitely the dev's fault and not the tool being held together with duct tape and vibes.

Tunde Obi2h

Blaming the tool is wild when the dev chose to type a diagram in markdown instead of exporting an SVG, so that duct tape mess is 100 percent on them fr

Sipho van der Merwe3h

Nah, it's a diagram problem, because the second your architecture lives in a second copy nobody compiles, it rots, and then you've got two lies instead of one

Palesa Ndlovu2h

L take, a stale diagram is still a diagram

Isha Bose13h

Yaar SVG export goes stale in two weeks max, mermaid at least lives in the same PR so the reviewer sees the actual change.

Shreya Sandhu10h

Bhai, so the reviewer is supposed to mentally render a 40 node flowchart out of a plain text diff, and that counts as seeing the actual change? If they never open the preview, which they don't, what is mermaid actually buying you over an SVG that also lands in the same PR and shows up as a changed file?

Mathieu Wilson7h

Bro reviewers absolutely open the preview, that is literally the entire reason the extension exists in the first place, and if yours don't then you have a code review problem, not a mermaid problem

Isha Bose4h

Nobody opens the preview because the diff is where review actually happens, and an SVG sitting there as a changed binary blob tells the reviewer even less than forty lines of text they can at least skim

Matheus Oliveira6h

Exactly. OP's stlae SVG is the real busywork, fr

Taylor Jackson5h

That reviewer scrolling past a 40 node mermaid blob in the diff isnt "seeing the change," they're rubber stamping wall of text they can't render in their head, so the SVG you commit in that same PR is literally the only version anyone can actually look at.

Olivia Allen2h

So who renders the SVG inside a git diff?

한서준13h

Typing it out is the whole point

Sneha Pandey12h

Typing it out is the only reason the thing stays correct, and a committed SVG is a dead blob nobody can edit in a PR without hunting down the source file, so congrats on inventing a screenshot with extra steps. The we-solved-this-in-2010 crowd was shipping stale Visio exports that nobody could open anyway, dark mode being broken is a theming bug, not an argument for going back to stone age

Chloe Jones9h

Sure, typing it keeps it editable, but editable by who? The same three people who never open the diagram anyway. An SVG nobody updates beats a 40 node flowchart nobody reads, and the build breaking on a syntax tweak is the most on brand outcome possible for docs cosplaying as code

Riya Rao8h

If the typed source is what keeps it correct, why does every one of these flowcharts describe an architecture from three refactors ago? Who's actually opening that PR to fix the nodes, or is "editable in a PR" just a nice story you tell yourself while the diagram rots in plain text instead of rotting as an SVG?

Naledi Ndlovu10h

Typing it out is the whole point for who exactly, the person typing it? Nobody reads a 40 node mermaid graph anyway, so you spent an hour on syntax and got zero comprehension out of it. An exported SVG shows the same thing, opens instantly, and doesnt shit the bed when some parser update changes an arrow style. Commit the image, keep the diff, move on, this isn't engineering, its cosplay.

Ashley Baker9h

Cope. Typing it is just busywork with extra steps

Aditi Tiwari5h

Sure, typing it keeps the diff readable and you don't ship a binary blob, credit where it's due. But nobody is reading your 40 node flowchart anyway, so you're just maintaining a parser and four extensions so a diagram with zero readers can stay in sync with code that changed last Tuesday.

Nicole Villanueva13h

A PNG in git is still documentation, stop pretending text is sacred.