Glonce

Reladraw is a text-based diagram language with relative positioning

toolsThe Glonce editorsHacker News🔥61Glonce rating61Impact42Novelty50Relevance70Surprise28Players12Credibility83
Reladraw is a text-based diagram language with relative positioning

A Show HN post introduces reladraw, a text-based diagram language and command-line tool now at version 0.8.0. Its pitch is a middle ground between two existing approaches to diagramming. Tools like Mermaid, Graphviz and D2 let a user declare boxes and connections and then auto-lay-out the positions, which the author says is not the right tool when you have a particular picture in mind. Tools like draw.io or Excalidraw allow absolute placement of every element, but that takes much more effort, whether from a human dragging nodes around or an AI agent recalculating coordinates and editing verbose XML source files. Reladraw instead uses relative positioning: a node can be declared "below" another, "right of" another, or "level with" another, so the author decides the overall arrangement without manually picking coordinates. An example snippet from the README defines a web app with a UI and API node, a database node placed to the right of and level with the app, and an edge connecting the API to the database labelled "queries". The compiler turns a .reladraw text file into an SVG. The parser, layout engine and SVG renderer are all written in TypeScript with zero runtime dependencies. The tool installs via npm (npm install -g reladraw) and runs from the command line (reladraw diagram.reladraw -o diagram.svg), or can be built from a cloned repository, which also includes example files. The project also ships an installable "skill" (via npx skills add reladraw/reladraw) that lets AI coding agents such as Claude Code, Codex, Cursor and Copilot know how to write reladraw diagrams; it can be installed globally for all agents, scoped to a single project, or targeted at one specific agent. The author describes the project as early stage but working, and warns that the language is not yet stable, so the syntax is expected to change. The code is released under Apache-2.0, but the license explicitly covers only the code, not the project's name, logo or other marks. The author asks for issues over pull requests while the language is still changing quickly, saying a diagram that reladraw could not represent is a particularly useful bug report.

Key facts

  • Reladraw is a text-based diagram language and CLI tool, currently at version 0.8.0, that compiles a .reladraw text file into an SVG
  • Instead of auto-layout (Mermaid, Graphviz, D2) or fully manual absolute placement (draw.io, Excalidraw), it uses relative positioning keywords like "below", "right of" and "level with"
  • The parser, layout engine and SVG renderer are written in TypeScript with zero runtime dependencies
  • It ships an installable skill (npx skills add reladraw/reladraw) so AI agents like Claude Code, Codex, Cursor and Copilot can generate reladraw diagrams
  • The code is Apache-2.0 licensed, but that license does not extend to the reladraw name, logo or other marks; the author calls the project early stage with an unstable syntax

Why it matters

Diagramming tools force a tradeoff: auto-layout languages like Mermaid are fast to write but give up control over the final picture, while fully manual tools like draw.io give total control but cost a lot of clicking, or, increasingly, a lot of AI-agent effort recalculating coordinates in verbose XML. Reladraw's relative-positioning approach tries to keep the speed of a text-based language while preserving the author's intended layout, which is also easier for an AI agent to generate reliably than exact coordinates.

Who it affects

Developers and technical writers who need custom-looking architecture or flow diagrams, and increasingly AI coding agents that are asked to produce diagrams as part of documentation or planning; the project explicitly targets both by shipping a skill file usable by Claude Code, Codex, Cursor, Copilot and other agents.

How to use it

Install with npm install -g reladraw, then compile a diagram with reladraw diagram.reladraw -o diagram.svg. It can also be run from a cloned repository via npm install && npm run build. To let an AI agent write reladraw diagrams, run npx skills add reladraw/reladraw -g for a global install across agents, drop the -g flag to scope it to the current project, or add -a claude-code (or another agent name) to target one agent specifically. The code is Apache-2.0 licensed, but that covers only the source, not the reladraw name or logo.

How solid is it

This is a Show HN post about the author's own open-source project rather than independently reviewed software. The README states the tool is early stage but working, with no performance benchmarks or usage figures given, and no name or maintainer details are provided beyond the GitHub project itself.

Risks and caveats

The author is explicit that the language is not yet stable and the syntax is expected to change, so diagrams written today may need updates with future releases. As an early-stage, single-maintainer project, it lacks the track record and ecosystem of established tools like Mermaid or draw.io, and the author is actively soliciting issues, especially diagrams that reladraw currently cannot represent, over pull requests while the language keeps changing.

“Mermaid, Graphviz and D2 let you declare boxes and connections, then determine positions for you. If you have a particular picture in mind, these aren't the right tool.”

— reladraw project README