I love making diagrams to help understand, plan, etc. However, the options are (A) auto-placement languages like Mermaid or Graphviz (which don't let me decide how the diagram looks), or (B) software like Draw.io which are powerful but are very time consuming (and inefficient for agents to manipulate).
I wanted to have the benefits of both, where you can define a diagram in a diagram language, but also retain a high degree of control over what the diagram looks like.
I also wanted this to work well for humans and agents.
On the Github link, there's a playground where you can try it out without installation. There's also instructions for a simple npm install and for installing a skill you can use with Claude or other agents.
Thanks! The big difference is that Pikchr uses "turtle" graphics (where a cursor walks along and draws shapes). Reladraw lets you state relationships and relative positions.
So, if you have a container with children, or multiple nodes off to the right of another, with links between them, adding or resizing one adjusts the rest, without re-specifying positions the way turtle graphics would require.
Thanks! I really like Mermaid, but if the diagram gets too complicated, it draws it how it wants and I end up reaching for Draw.io, which is also awesome, but can take a lot of time.
Fighting with mermaid is so frustraiting, especially when it comes to normal vs github formatting. This is going to replace several ad-hoc half impls I have laying around
Glad to hear it :) If you find that you want Reladraw to do something that it can't, let me know! I keep uncovering features by looking at actual Draw.io diagrams I've made and seeing if Reladraw can do it.
This is basically tikz's positioning library (right=of, below left=of) without having to touch LaTeX. With tikz it was never the nodes that hurt me, it was the edges. Once two edges want the same side of a box it gets ugly fast. Does the resolver do any routing, or is from:/to: all you get? And what happens with conflicting statements, does the first one win or do you get an error?
Does the resolver do any routing?
It doesn't auto-route around obstacles. But, if nodes A, B, and C all have edges going to the left side of D, they share that side and space themselves apart so they don't cross. If the side is too short, they'll bow out to make space for each other, so you don't have to manually fiddle. You can also give routing instructions like "these edges pass between these two nodes on their way to D".
Conflicting statements?
Statements that can all hold will all apply. Right of one node and below another is okay. Or, "right of A and B and C" will clear whichever sticks out furthest. If they all can't hold, you'll get an error naming the clashing statements (e.g., something both left and right of A). Nothing silently wins.
Thanks! My concern was that a resolver making decisions "to be helpful" could become surprising or frustrating.
For example, if you ask for edges to pass "between C and D", but those two nodes sit diagonally, the gap you are asking for might be the vertical channel or horizontal channel between them. So instead of guessing for you, it will tell you of the ambiguity and let you spell out what you want.
Great idea! So, right now it defaults to this sorta "dark" theme, and the only option you'd have is to change the diagram background color or define styles. I'll make defining some preset themes a priority!
That is damn interesting. When I made copilot write a script that creates a .dot diagram, I found it funny that it had the same problems with placement that I have when doing it manually.
Thanks very much! Yea, with .dot, the layout engine decides where things go. So, the agent doesn't know what the result looks like, leading to render, look, fiddle loops. And, depending on how much you care about layout, .dot might not give you enough knobs to turn to make it look like what you want.
The idea with Reladraw is that a human or agent could just state "I want this node to the right of this other one", rather than have a layout engine decide. Hopefully less fiddling for agents!
Thanks! Mermaid is so cool, but I wanted this relative placement, too. I've played with having Claude make me infographics in HTML and also using SVG. They can be surprisingly decent, until you want something complicated, then it gets messy! I figure, let the agents just say what they want, and let the tool (Reladraw) worry about the arithmetic. No use having an agent burning tokens to recompute coordinates with dubious results! >.<'
I wish this just implement tikz without latex. I've yet to see a better drawing library that is both simple and has the depth to build the most complicated things.
tikz looks super powerful. Reladraw is opting for a narrower job - making diagrams with boxes, groups, arrows, where you can say relative positions and let Reladraw save you extra work.
Bug is fixed in the playground. Thanks again for catching it!
It gave me some ideas to make routing better, too. For example, maybe you don't want the edge to curve above, but rather below. Or, in more complex examples, maybe you want the edge to curve above one thing and to the right of another.
Mermaid works great for fixed layouts like sequence diagrams and Gantts. For flowcharts, where position is king, it's bad.
I've tried using svg in my MD files but they get unwieldy quite fast. This is a great idea. My first reaction was - but what's if I need something more exact. But reflecting on it, I've realized that this relative positioning is probably enough.
Yea, it's hard to beat absolute positioning if you want something ultra-custom, but I'm hoping for most flowcharts, mind maps, etc. the relative positioning is enough to get what you want without fiddling too much!
That’s what I have been using, but from glancing through this repository, it looks like the win here is that you can define where you want things and yet still have diagram as code
Yep, exactly! D2 is in the same family as Mermaid, i.e., automatic layout, with some escape hatches like grid placement or absolute positioning. Reladraw sits in a gap between automatic layout and absolute positioning.
Does this need to be shipped with a renderer? A better question is, are the node layout instructions ultimately being translated into absolute positions?
If so, you could target any number of render backends, keeping the same simple interface for your agent, avoiding the bazillion problems rendering engines face to work well across the ecosystem.
Great idea! Yep, the layout instructions are translated into absolute positions. The one gap right now is just that the CLI doesn't give you a way to say "just calculate the positions, stop there, and give me JSON". The logic basically exists to do that, with a minor tweak to the CLI to allow that.
That's a very thought-provoking question. Adding placement constraints on top of an automatic layout engine sounds like a challenging problem. You'd have the engine deciding where to place things, but you'd also be nudging things or constraining things.
This might not be what you have in mind, but Graphviz has a `rank` which can be used as a coarse way to influence the shape of the diagram. (I'm assuming you had something more sophisticated in mind though)
Probably easier would be if the relative drawing were its own distinct Mermaid diagram type, but then it would be largely a new language anyway.
This is very needed in the AI coding age! I find diagramming is one of the best ways for high bandwidth alignment between my mental model and the agent’s. I have been working on this problem a bit as I see good visuals as a key bottleneck in faster development while maintaining a real architecture.
Will def be adding this to my list of diagramming tools the agent can use!
It's funny, you articulated it very similar to how I feel! Seems like we need ways to maintain mental models at a high enough level of abstraction when working with agents.
There's a skill in the repo that you can install using `npx skills` to get started with. I'm sure the integration of Reladraw with agents can be made way better, though. It's just a bit... basic/rudimentary right now!
interesting. wonder how agents themselves can create something complex. I'll use it for sure. I direct my agents to [Graphviz provider](https://graphviz.rodmena.co.uk/)s these days.
1. awesome ~ this seems to be in a sweet spot! (yes, mermaid is fine; but often looks bad - esp when visualizing large diagrams)
2. it would be great to have this as a layouting layer for C4
3. which brings me to a suggestion: i think it would make sense to allow for decoupling the topological parts of the language (arrows, groupings, etc) from the layouting concerns (left of, right of, etc)
I wanted to have the benefits of both, where you can define a diagram in a diagram language, but also retain a high degree of control over what the diagram looks like.
I also wanted this to work well for humans and agents.
On the Github link, there's a playground where you can try it out without installation. There's also instructions for a simple npm install and for installing a skill you can use with Claude or other agents.
Great! Reminds me of Pikchr a bit https://pikchr.org/home/doc/trunk/homepage.md
Thanks! The big difference is that Pikchr uses "turtle" graphics (where a cursor walks along and draws shapes). Reladraw lets you state relationships and relative positions.
So, if you have a container with children, or multiple nodes off to the right of another, with links between them, adding or resizing one adjusts the rest, without re-specifying positions the way turtle graphics would require.
I like it. I have too many issues with Mermaid
Thanks! I really like Mermaid, but if the diagram gets too complicated, it draws it how it wants and I end up reaching for Draw.io, which is also awesome, but can take a lot of time.
This genuinely fucks. Thank you
Fighting with mermaid is so frustraiting, especially when it comes to normal vs github formatting. This is going to replace several ad-hoc half impls I have laying around
Glad to hear it :) If you find that you want Reladraw to do something that it can't, let me know! I keep uncovering features by looking at actual Draw.io diagrams I've made and seeing if Reladraw can do it.
(since you ask...) Edges drawn with right angles would be a nice option.
Great idea! Adding to the todo list.
o7 will do, and if I cook anything up I think you might appreciate I'll try and yeet over a nice PR
Thanks!
This is basically tikz's positioning library (right=of, below left=of) without having to touch LaTeX. With tikz it was never the nodes that hurt me, it was the edges. Once two edges want the same side of a box it gets ugly fast. Does the resolver do any routing, or is from:/to: all you get? And what happens with conflicting statements, does the first one win or do you get an error?
Appreciate the comment and questions!
Does the resolver do any routing? It doesn't auto-route around obstacles. But, if nodes A, B, and C all have edges going to the left side of D, they share that side and space themselves apart so they don't cross. If the side is too short, they'll bow out to make space for each other, so you don't have to manually fiddle. You can also give routing instructions like "these edges pass between these two nodes on their way to D".
Conflicting statements? Statements that can all hold will all apply. Right of one node and below another is okay. Or, "right of A and B and C" will clear whichever sticks out furthest. If they all can't hold, you'll get an error naming the clashing statements (e.g., something both left and right of A). Nothing silently wins.
Fantastic! Never change this.
People will complain. These people also prefer type unsafe languages. Hold fast.
Thanks! My concern was that a resolver making decisions "to be helpful" could become surprising or frustrating.
For example, if you ask for edges to pass "between C and D", but those two nodes sit diagonally, the gap you are asking for might be the vertical channel or horizontal channel between them. So instead of guessing for you, it will tell you of the ambiguity and let you spell out what you want.
I was looking for something like this. I wish it had different themes, the will prob be the best improvement.
Great idea! So, right now it defaults to this sorta "dark" theme, and the only option you'd have is to change the diagram background color or define styles. I'll make defining some preset themes a priority!
Just pushed an update to add a basket of themes, including light and dark themes.
That is damn interesting. When I made copilot write a script that creates a .dot diagram, I found it funny that it had the same problems with placement that I have when doing it manually.
Thanks very much! Yea, with .dot, the layout engine decides where things go. So, the agent doesn't know what the result looks like, leading to render, look, fiddle loops. And, depending on how much you care about layout, .dot might not give you enough knobs to turn to make it look like what you want.
The idea with Reladraw is that a human or agent could just state "I want this node to the right of this other one", rather than have a layout engine decide. Hopefully less fiddling for agents!
I love it, and I wish it was part of Mermaid. I've always struggled with the presentation and agents tend to hack or just straight use SVG lol
Thanks! Mermaid is so cool, but I wanted this relative placement, too. I've played with having Claude make me infographics in HTML and also using SVG. They can be surprisingly decent, until you want something complicated, then it gets messy! I figure, let the agents just say what they want, and let the tool (Reladraw) worry about the arithmetic. No use having an agent burning tokens to recompute coordinates with dubious results! >.<'
I wish this just implement tikz without latex. I've yet to see a better drawing library that is both simple and has the depth to build the most complicated things.
tikz looks super powerful. Reladraw is opting for a narrower job - making diagrams with boxes, groups, arrows, where you can say relative positions and let Reladraw save you extra work.
Huh, can you read my mind?! :D
This is super cool. I love diagrams, charts, etc. and use them a lot. Both privately and for work.
Definitely going to make use of this, I didn't know how much I wanted something like this until right now hahaha.
Glad to hear it! I'm a big fan of diagrams for understanding, mapping out architecture, etc!
Seems a little buggy, I added this line:
edge parser -> renderer "test edge" from: left to: right
and it wasn't smart enough to make a curved arrow
Genuine bug! Good find. I'll look into a fix.
Bug is fixed in the playground. Thanks again for catching it!
It gave me some ideas to make routing better, too. For example, maybe you don't want the edge to curve above, but rather below. Or, in more complex examples, maybe you want the edge to curve above one thing and to the right of another.
(will update npm shortly too)
Mermaid works great for fixed layouts like sequence diagrams and Gantts. For flowcharts, where position is king, it's bad.
I've tried using svg in my MD files but they get unwieldy quite fast. This is a great idea. My first reaction was - but what's if I need something more exact. But reflecting on it, I've realized that this relative positioning is probably enough.
Yea, it's hard to beat absolute positioning if you want something ultra-custom, but I'm hoping for most flowcharts, mind maps, etc. the relative positioning is enough to get what you want without fiddling too much!
Agreed. Next diagram I make I’m taking a photo of a whiteboard and letting AI figure out relative positioning
That sounds very cool :)
https://d2lang.com/ works well?
That’s what I have been using, but from glancing through this repository, it looks like the win here is that you can define where you want things and yet still have diagram as code
Yep, exactly! D2 is in the same family as Mermaid, i.e., automatic layout, with some escape hatches like grid placement or absolute positioning. Reladraw sits in a gap between automatic layout and absolute positioning.
D2 has some support for this. You can fix the position of certain elements and then it will redraw things around it.
I’ve been thinking about something similar to this but D2 wasn’t totally open source until now.
Does this need to be shipped with a renderer? A better question is, are the node layout instructions ultimately being translated into absolute positions?
If so, you could target any number of render backends, keeping the same simple interface for your agent, avoiding the bazillion problems rendering engines face to work well across the ecosystem.
Great idea! Yep, the layout instructions are translated into absolute positions. The one gap right now is just that the CLI doesn't give you a way to say "just calculate the positions, stop there, and give me JSON". The logic basically exists to do that, with a minor tweak to the CLI to allow that.
I'll add that to my Reladraw todo list!
Mermaid is open source, no? Can we just add these placement constraints to Mermaid instead of making a whole new language?
That's a very thought-provoking question. Adding placement constraints on top of an automatic layout engine sounds like a challenging problem. You'd have the engine deciding where to place things, but you'd also be nudging things or constraining things.
This might not be what you have in mind, but Graphviz has a `rank` which can be used as a coarse way to influence the shape of the diagram. (I'm assuming you had something more sophisticated in mind though)
Probably easier would be if the relative drawing were its own distinct Mermaid diagram type, but then it would be largely a new language anyway.
If this were implemented in a language with fewer dependencies, it'd be great.
Reladraw has no runtime dependencies and Typescript is only needed to build it. If you mean Node, though, that's fair!
Maybe a couple of binaries? https://github.com/vercel-labs/scriptc
Oh wow. Let me give that a try. I was going to try bun or Deno, but your suggestion might result in much smaller binaries.
This seems nice but I’ll need to read the syntax more carefully to see how capable and convenient it is.
Definitely! Capability vs convenience is tough! Hope you find it useful.
This is very needed in the AI coding age! I find diagramming is one of the best ways for high bandwidth alignment between my mental model and the agent’s. I have been working on this problem a bit as I see good visuals as a key bottleneck in faster development while maintaining a real architecture.
Will def be adding this to my list of diagramming tools the agent can use!
It's funny, you articulated it very similar to how I feel! Seems like we need ways to maintain mental models at a high enough level of abstraction when working with agents.
There's a skill in the repo that you can install using `npx skills` to get started with. I'm sure the integration of Reladraw with agents can be made way better, though. It's just a bit... basic/rudimentary right now!
interesting. wonder how agents themselves can create something complex. I'll use it for sure. I direct my agents to [Graphviz provider](https://graphviz.rodmena.co.uk/)s these days.
That's cool! I'm curious to see how it goes if you try making some super complex :)
1. awesome ~ this seems to be in a sweet spot! (yes, mermaid is fine; but often looks bad - esp when visualizing large diagrams)
2. it would be great to have this as a layouting layer for C4
3. which brings me to a suggestion: i think it would make sense to allow for decoupling the topological parts of the language (arrows, groupings, etc) from the layouting concerns (left of, right of, etc)