Reladraw: Relative-Placement Diagrams vs Mermaid, D2

Reladraw is a text-based diagram language that positions nodes using relative statements — right of, below, level with — instead of absolute coordinates. The developer describes it as sitting between automatic-layout tools like Mermaid and Graphviz and manual-placement tools like draw.io and Excalidraw. It appeared on Hacker News on September 26, 2026 as "Show HN: Reladraw – A diagram language where you decide where to place things," reaching 310 points and 83 comments within about 16 hours.

In short, Reladraw addresses a gap between two existing camps of diagramming tools: automatic layout tools that don't let you decide the final look, and manual tools that are slow to write and poorly suited to AI agents. It never asks you to write a single coordinate, yet placement intent — which node sits to the right, which two are level with each other — stays explicit in the text, aiming for a format that's easy for humans to read and write and easy for AI agents to review as a diff. The repository is published at reladraw/reladraw; as of this writing it has 549 stars, is written in TypeScript, is licensed under Apache-2.0 (code only — the name and logo are excluded), and sits at v0.8.0, an early stage where the syntax is still expected to change.

In Reladraw's syntax, node declares a node, and keywords like below, right of, and level with position it relative to an existing node. Chaining node names with dots (app.ui) expresses nested groups, and edge draws an arrow between nodes, with from: and to: specifying which side it leaves from and arrives at.

When positioning statements conflict — for example, telling the same node to sit both right of and left of another — Reladraw raises an error instead of silently resolving it the way automatic-layout tools tend to. Edges are routed around other nodes automatically and drawn with right-angle corners. Multiple themes (color and line-style presets) were also added recently, letting you switch the look without hand-tuning CSS-like settings.

Reladraw is free, open-source software with no paid tier. Install it standalone via npm, or build it from source.

For coding agents such as Claude Code, Codex, Cursor, and GitHub Copilot, a dedicated skill is available. Adding it globally with npx skills add reladraw/reladraw -g lets an agent understand Reladraw's syntax on the spot and generate or edit diagrams directly.

The shortest workflow is to write the syntax into a .reladraw text file, convert it to SVG with the CLI, and embed the result directly into Markdown or documentation.

The generated SVG can be dropped in as an image, and because the text source (the .reladraw file) itself is version-controlled in Git, reviewers can read diffs the same way they would for code. Used through an agent, adding the skill above lets you simply ask in natural language — "draw the architecture for this API" — and the agent generates the node/edge syntax and, if needed, runs the CLI to produce the SVG in one pass. Compared with the diagram-design skill for Claude Code, which has an agent generate brand-styled diagrams, Reladraw takes a different, lighter-weight approach that prioritizes locking down intended placement in text over decoration.

Diagramming tools broadly fall into three camps: automatic layout, manual placement, and relative placement (Reladraw).

Mermaid, Graphviz, D2, and PlantUML compute node positions with an automatic layout engine, which means less writing but sometimes an unwanted layout with limited or no room to fine-tune it. draw.io and Excalidraw go the other way, offering free drag-and-drop placement at the cost of a text representation, which makes them awkward for Git-based review or automated editing by an AI agent. TikZ assumes LaTeX, carries a steep learning curve, and stays narrowly scoped to boxes and arrows. This same automatic-vs-manual framing is central to the Hacker News discussion of Reladraw, where the author explains the motivation as: automatic placement doesn't let you decide the look, and manual placement is slow to write and poorly suited to AI agents. Related agent-oriented diagram tools in this space include archify, which specializes in generating architecture diagrams, and Whiteboard, which reviews an agent's code changes on a canvas — each tool carving out its own niche.

- Fits people who want to lock down placement intent in text without hand-computing coordinates — a candidate if Mermaid or D2 keep producing layouts you didn't intend
- Fits workflows where an AI agent generates or edits diagrams: it can be installed as a skill via npx skills add, and its simple syntax is easy for an agent to generate
- Still early at v0.8.0, and the syntax is expected to change. Budget for keeping up with version changes if embedding it into a production documentation pipeline
- With 549 stars and 6 forks, its community is still much smaller than Mermaid's or D2's, and official Obsidian or VS Code extensions were not yet available as of the Hacker News discussion (users have requested them)
- Output is SVG only; converting to PDF or PNG requires a separate tool
- For complex automatic graph layout — cleanly auto-arranging large numbers of nodes — Graphviz or D2 remain a better fit. Because Reladraw makes placement explicit, the amount you write grows with the number of nodes
- Licensed under Apache-2.0, but the Reladraw name and logo are excluded, so forks or redistributions need to handle naming carefully

Reladraw is a diagram language that fills the gap between automatic layout (Mermaid, Graphviz, D2, PlantUML) and manual placement (draw.io, Excalidraw, TikZ) with a relative-placement approach. By leaving coordinate math to the tool while keeping placement intent explicit in text, it's designed with AI agent compatibility in mind. It's still early at v0.8.0 and the syntax may change, but the ease of dropping it into an agent via npx skills add places it, alongside tools like archify and Whiteboard, among the emerging directions for diagramming in the age of AI agents.