my-hermes-skills

Should Reladraw replace Mermaid for README diagrams?

Abstract

Background. Reladraw, shown on Hacker News around 2026-09-27[1], is a diagram language in which the author places elements relative to each other instead of leaving layout to an engine. Mermaid is the usual choice for diagrams in GitHub READMEs and docs.

Objective. To decide whether Reladraw should replace Mermaid for diagrams in GitHub READMEs and docs.

Methods. GitHub's diagram documentation[2], the Reladraw README[3], Mermaid's introduction[4] and Reladraw's syntax reference[5] were read alongside the Show HN thread[1], an editor extension[6] and an alternative raised there[7]; npm metadata was queried. One diagram was rendered locally with both CLIs, timing 3 warm runs.

Results. GitHub renders only four fenced diagram syntaxes (mermaid, geojson, topojson, stl)[2], so a reladraw block shows as plain text. Reladraw is at v0.19.0 with its syntax still changing[3]. Locally, Reladraw rendered in 0.17-0.19 s versus 0.59-0.64 s for Mermaid and produced a 1,632-byte SVG versus 197,763 bytes (measured).

Conclusions. Keep Mermaid for anything that must render inline in a GitHub README, issue or PR; use Reladraw only for hand-placed architecture or flow diagrams that you are willing to render to SVG and commit, or show on a Pages site.

1. Introduction

Diagrams in this repository's READMEs and skills site are written in Mermaid, which GitHub renders natively. Reladraw proposes a different model: declare where things go relative to each other, and the tool never moves anything[3]. Its own README frames it as filling the gap between auto-layout languages (Mermaid, Graphviz, D2) and absolute-placement tools (draw.io, Excalidraw), not as a full Mermaid replacement[3].

2. Methods

2.1 Sources and search strategy

Fetched 2026-10-24: the Reladraw Show HN thread[1], GitHub Docs "Creating diagrams"[2], the Reladraw README[3], the Mermaid intro docs[4] and Reladraw SYNTAX.md[5]. The VS Code extension[6] and the TALA layout engine[7] were followed from the HN thread. npm registry metadata (versions, publish dates) was queried on 2026-10-24; no reference URL was recorded for it.

2.2 Evidence classification

2.3 Experimental setup

One diagram was rendered locally with both CLIs (reladraw 0.19.0, @mermaid-js/mermaid-cli 12.0.0 / mermaid 12.x) on macOS, Node via npx; timings are 3 warm runs plus one cold first render. Diagram: a "Web app" container holding Interface above API, API -> Database labelled "queries". Times include npx startup. Mac model and Node version were not recorded.

2.4 Analysis

Descriptive comparison; ranges are min-max over the 3 warm runs.

3. Results

3.1 Feature comparison (RQ1, RQ2)

Table 1. Mermaid and Reladraw compared (vendor-reported unless marked).

DimensionMermaidReladrawSource
Core ideaDeclare nodes/edges; layout engine decides positionsDeclare where things go relative to each other; tool never moves anythingMermaid docs[4]; Reladraw README[3]
Renders natively in GitHub markdownYes (``` `mermaid ``` fence; Issues, PRs, wikis, Discussions, .md files)No - must pre-render SVG and embed as imageGitHub Docs[2]
Diagram typesMany dedicated types: flowchart, sequence, class, state, Gantt, ER, git graph, user journey, quadrant, XY chart, use case (beta) and moreOne generic language (nodes, edges, points, regions, bundles); flowchart shapes built in; no dedicated sequence/Gantt/class syntaxMermaid intro[4]; Reladraw SYNTAX.md[5]
Layout controlLimited; direction, subgraphs, layout engine choice (e.g. ELK)Full relative control: right of, below, even with, gaps, fractions, waypointsSYNTAX.md[5]
Problem reportingParse errors; layout surprises are silentDraws exactly what is written, prints one-line findings (line through box, overlapping text); reladraw check; contradictions are errorsReladraw README[3]; HN author replies[1]
Edge routingAutomaticNo auto-routing around obstacles; edges sharing a side space themselves; manual waypointsHN author reply[1]
Maturityv12.2.0 (npm, 2026-10-13); long-running project, MITv0.19.0 (npm, 2026-10-23); "language is changing frequently"; 0.17.0 had large breaking renames; Apache-2.0; no PRs accepted (issues only)npm; Reladraw README/SYNTAX.md[3, 5]
Web embeddingmermaid JS from CDNOne script, <reladraw-diagram> custom elementboth docs[3, 4]
Agent toolingWidely known to LLMsShips an agent skill: npx skills add reladraw/reladraw -gReladraw README[3]
Editor supportMany integrations (Obsidian, GitLab, Notion, VS Code)Community VS Code extension for markdown preview (volkanunsal/relative-diagrams-vscode)[6]HN thread[1]

3.2 Local render test (RQ3)

Table 2. Local render test, 2026-10-24 (measured).

MetricMermaid (mmdc 12.0.0)Reladraw 0.19.0
Warm render time (3 runs)0.59-0.64 s0.17-0.19 s
Cold first render2.39 s0.66 s
Output SVG size197,763 bytes1,632 bytes
Installed sizemermaid 125 MB + @mermaid-js 48 MB1.1 MB, zero runtime deps
Source lines75

Both rendered correctly. Mermaid's result placed Interface above API by its own layout choice; Reladraw placed it because the file says below app.ui.

4. Discussion

4.1 Principal findings

RQ1 decides the README case: a reladraw block cannot render inline on GitHub[2]. RQ2: Reladraw is not a Mermaid replacement in general. It is one generic "boxes and lines with relative placement" language at v0.19.0 with syntax still changing[3], while Mermaid is a mature multi-diagram-type tool[4] with native rendering on GitHub[2]. Where Mermaid is weak, in flowcharts and architecture diagrams where position matters most[1], Reladraw is the stronger tool; where Mermaid is strong (sequence diagrams, Gantt, class/ER), Reladraw has no dedicated syntax. Reladraw is deterministic and loud, which suits agent-edited diagrams because the agent gets actionable warnings. RQ3: on one small diagram Reladraw was faster, far smaller in output and install size, and equally correct. The SVG size difference is mostly Mermaid's embedded styles/fonts (ASSUMPTION: not inspected byte-by-byte).

4.2 Comparison with prior work

HN commenters proposed other placement-aware options, notably D2 with TALA[7]; these were not evaluated here.

4.3 Practical implications

5. Limitations

6. Conclusion

Mermaid should stay as the README diagram tool because GitHub renders it inline and does not render Reladraw. Reladraw is a better fit for hand-placed architecture and flow diagrams when rendering to a committed SVG or a Pages site is acceptable, with its version pinned while the language is still changing.

References

  1. [1] Show HN: Reladraw - A diagram language where you decide where to place things (Hacker News, ~2026-09-27): https://news.ycombinator.com/item?id=49858513 back to text 1 2 3 4 5 6 7 8 9 10 11 12 13
  2. [2] Creating diagrams (GitHub Docs): https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-diagrams back to text 1 2 3 4 5 6 7 8
  3. [3] reladraw/reladraw (GitHub README, v0.19.0): https://github.com/reladraw/reladraw back to text 1 2 3 4 5 6 7 8 9 10 11 12 13 14
  4. [4] About Mermaid (Mermaid docs): https://mermaid.js.org/intro/ back to text 1 2 3 4 5 6 7
  5. [5] reladraw SYNTAX.md (syntax reference 0.19.0): https://github.com/reladraw/reladraw/blob/main/SYNTAX.md back to text 1 2 3 4 5 6 7
  6. [6] relative-diagrams-vscode, render Reladraw diagrams in the VS Code Markdown preview (Volkan Unsal, GitHub): https://github.com/volkanunsal/relative-diagrams-vscode/ back to text 1 2 3
  7. [7] TALA layout engine (D2 Documentation): https://d2lang.com/tour/tala/ back to text 1 2 3 4