Reladraw: Manual Layout Diagram Language
Most diagram tools treat you like you can't be trusted with a ruler. You drag a box, and the whole graph rearranges itself like it's mad at you. Try to align two nodes and the software decides your layout is "inelegant" and "optimizes" it into something that looks nothing like what you had in mind.
Reladraw takes the opposite approach. You place every element exactly where you want it, and it stays there. No auto-layout surprises, no "helpful" reflows, no fighting with invisible springs and repulsion forces that seem to have opinions about aesthetics you don't share. It's the difference between sketching on paper and wrestling with a physics engine.
This matters more than it probably should. I've spent hours in tools that think they know better, manually overriding algorithms that insist my diagram would look "better" if it followed their rules. Reladraw assumes you know what you want, which feels almost radical in a world where most software is designed to prevent you from making mistakes — including the mistake of wanting control in the first place.
What happens when a diagramming tool stops trying to be your editor and starts being your drafting table?
What Makes Reladraw Different
Most diagramming tools make a tradeoff: you either get automatic layout engines that rearrange your elements based on heuristics, or you get manual placement that feels clunky and afterthoughted. Reladraw takes the opposite approach. Every element gets explicit coordinates. There's no "smart" algorithm deciding where your boxes should go. If you write box "Hello" at 100, 50, that box is at 100, 50. Period.
This isn't an accident of implementation — it's the whole point. The declarative syntax reads like you're giving directions:
box "Database" at 0, 0
box "API Server" at 200, 0
arrow from "Database" to "API Server"You specify what goes where, and Reladraw draws exactly that. No fighting with auto-layout engines that insist your boxes need to be spaced 127 pixels apart, or that labels should be rotated 30 degrees for "optimal readability." If you want two boxes overlapping, you put two boxes overlapping.
Version 0.8.0 ships as a TypeScript implementation with zero runtime dependencies. It's Apache-2.0 licensed, which means you can drop it into a build pipeline without worrying about license compatibility. The comparison to Pikchr makes sense — both tools trust the user to specify layout rather than impose it. That's a deliberate choice, not a limitation.
The tradeoff is obvious: you give up the convenience of letting a tool figure out placement for you. But if you've spent enough time wrestling with Mermaid diagrams that keep rearranging themselves every time you add a new node, you start to appreciate a tool that does exactly what you tell it.
How It Works
The parser is written entirely in TypeScript with zero runtime dependencies, which means you can drop it into a project without pulling in a dozen transitive packages. The language itself is declarative, so you describe what you want rather than how to draw it. You specify coordinates for points and declare relationships between them, and the system figures out the geometry.
Here's how that looks in practice:
import { parse } from 'your-parser-name';
const source = `
box "Hello" as hello
box "World" as world
arrow from hello to world
`;
const svg = parse(source);The output is SVG generated directly from the parsed definitions — no intermediate rendering step, no canvas, no browser dependency for the core logic. That makes it work the same way in Node, in a browser, or embedded in a documentation pipeline.
The Apache-2.0 license means you can use it in commercial projects without any licensing friction. That matters more than it should, coming from someone who's spent too much time untangling license compatibility issues.
One thing worth noting: the declarative approach works well when your diagrams are mostly about spatial relationships and positioning. If you're doing something highly procedural or need fine-grained control over individual path elements, you might find yourself working against the model. But for most technical diagrams, specifying "put this here, connect it to that" is exactly what you want.
Practical Usage Patterns
Positioning elements by explicit coordinates is the core workflow. You place nodes with x and y values, then define connections between them using arrow syntax. This is straightforward, but it does mean you're thinking in relative terms — "this node goes 200 pixels right of that one" rather than letting a layout engine handle the spacing. For diagrams with dozens of elements, that gets tedious fast.
Styling and grouping capabilities are where it starts to feel useful. You can set fill colors, stroke widths, and text styles inline, and group related elements so you can move them together. The styling syntax is minimal — no cascading rules or themes — which keeps things simple but means you'll repeat yourself if you're applying the same look across multiple diagrams.
Integration into existing documentation workflows hinges on the build process. Since it's a TypeScript tool with zero runtime dependencies, you can drop it into a Node-based pipeline without worrying about extra packages. The Apache-2.0 license means no legal friction for most projects. A typical setup looks like this:
npm install --save-dev @markdoc/markdocOne thing that stands out: the syntax borrows from Pikchr, which itself was designed for embedded diagramming in docs. That lineage shows in how it prioritizes readability over terseness — you write more to get cleaner output. Whether that tradeoff pays off depends on your tolerance for verbose markup versus fighting with a layout engine that doesn't quite place things where you want.
When Reladraw Fits Your Workflow
The copy-on-run behavior is the biggest workflow adjustment. Run a reladraw command today, and you get that exact version frozen in your output — useful for reproducible builds, annoying when you forget to re-run after a release. I've been caught by this twice already. It's not like calling an external tool where you always get the latest; this is more like committing a binary dependency. Good for determinism, bad for muscle memory.
The diagramming tool itself feels genuinely better than Mermaid for certain use cases. The positioning system actually works the way you think it should, and that's not something I can say about every diagramming solution I've used. I watched a user go from frustrated to fluent in about twenty minutes, which is a faster ramp than I'd expect from any new diagramming tool.
Themes are the obvious gap, and the community knows it. The default styling is clean enough, but if you want anything beyond the base palette, you're hand-writing CSS. That feels like the next priority, and not because the core tool is incomplete — because adoption often lives in the details of customization.
I'm curious whether the copy-on-run model will scale as the tool evolves. It makes sense for stable releases, but it could get painful if the team pushes frequent minor updates. The question isn't whether this approach works — it clearly does — but whether users will consistently remember to refresh when they should.
Conclusion
Reladraw's insistence on re-running every release feels like a deliberate middle finger to the "set it and forget it" mentality that dominates diagramming tools. You want a snapshot of your skill at version 0.8.0? Run the command. New release drops? Run it again. No magic syncing, no auto-updating canvases—just you and your terminal, doing the work.
That's either refreshingly honest or needlessly punitive, depending on your tolerance for manual processes. The TypeScript implementation with zero runtime dependencies is genuinely nice, and relative positioning solves a real pain point without the verbosity of XML or the guesswork of absolute coordinates. But making users re-execute commands for every update? That's not a feature—it's a constraint masquerading as purity.
I'm still not sure whether this is the future of diagram-as-code or just a clever experiment that happens to compile.