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!
Won’t it be a good idea to stay at the visual level?
Instead of generating visuals from text and then back to text, just communicate visually with your agents.
Something like UML provides a certain granularity to be able to code something usefully in pure visual language. Of course there are other visual programming languages that provide more depth and would probably be better suited.
Point remains that a solution based on constantly mapping better two different representations of the same thing won’t be a long term efficient solution.
For my part, I've found Literate Programming to be the best lever on this for my own work, and there has been some discussion of other folks being successful applying it to LLM work:
> 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.
D2's layout engine TALA [1] actually allows you to provide a lot of manual control. TALA used to be commercial, but is now open source.
In my own testing, TALA tends to produce much better layouts than Mermaid, including the ELK layout algorithm (which is not Mermaid's default; D2 also supports ELK).
TALA supports controlling direction per container, defining which shapes have to be near each other, and so on. I've not played with this yet, though.
Thanks for mentioning TALA. I feel like TALA does add more control than Mermaid, but in spirit sits closer to Mermaid than Reladraw. It keeps the auto layout, but with extra ways to coax the diagram into a different shape, by saying things like "keep this node pinned over here" or "keep these nodes close to one another".
For the diagrams I usually want to create, that's still not enough control to create what I envision.
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.
This is just for me, but I don't think I want to get into the business of specifying placement in that much detail. It would too cumbersome and I'd rather focus on what I want the diagram to convey, rather than how.
Thanks for making that! Just a heads up, reladraw is changing super fast - I think the rendering/highlighting will work smoothly with syntax changes, the more annoying thing would be any JS API breaking changes.
No problem! I hooked up dependabot to detect upstream changes, so when you bump up the version number, it should create a PR and bump the version number of the extension, and I will merge. I think the unit tests should catch any regression.
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!
I'm guessing we're seeing actual religions appear, human effort potentially being blessed and machine being the work of Satan. It feels like those times are emerging, to me where people are inventing new religions out of fear of meaninglessness.
Why does Claude output being shown to humans mandate it be rewritten before before consumption? What school of thought is that from?
Snark humor: We are not in The Name Of The Rose and this code is not Aristotle's forbidden second volume of Poetics which is antithetical to the teachings of Christ and is deserving to being hidden in a labyrinth by Benedictine monks.
Absolutism as a philosophy sort of supports fanaticism. Absolute Certainly could be the religion which is being formed here during this onset of AI challenging humanity's utility.
The best looking diagram library where you can explicitly place elements IMO is schemdraw (python). Ironically it is a library for drawing electronic circuit diagrams with some flowchart functionality on the side.
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 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.
That's an interesting idea, and an unexplored design space. Graphviz's dot has rank and head/tail ports, and Plantuml's class diagram has some support for relative position, but both are more hints for the layout engine, not deterministic declarations. If I had a nickel for every hour I spent fiddling with a Plantuml diagram to get the relation directions to force the layout into at least an approximation of what I wanted, I'll be a lot closer to retirement.
I like that you're going for one generic syntax instead of many specific ones, like mermaid and Plantuml, but it's as much as a pro as it is a con, it's one reason why these languages evolved in the first place, instead of everyone just using DOT. One possible mitigation would be some sort of reuse mechanism? Some way that generic nodes could be defined once and instantiated many times, so if I wanted to draw something like a sequence diagram, I could define/change my participant lanes just once.
Another issue the "No multi-line statements, no line continuations, no blocks." philosophy. I get *why* you chose it, and has its advantages, but it's a pretty annoying constraint, specially if one wants to have longer node names, or have more detailed description of the node in its label, like listing the responsibilities of a class, for instance. "No blocks" is something that can probably won't make much difference, but line continuations (i.e., some distinction between physical and logical lines) can make or break the user experience, IMHO
The syntax for line breaks is another thing I urge you to reconsider, '/' is waaay to common of a character, and being forced to write long strings in a single line can get *really* annoying. Some sort of multiline string support would really make your existing syntax shine.
The last two suggestions/complaints would complicate your parser a lot, specially since you're writing it manually, so, they are trade offs, but as a user who'd love to have something like this on my toolbelt, not having these features would make me hesitate a lot on investing time in this tool.
That said, it's a nice idea, I'll keep an eye on it =)
Thanks! Some serious food for thought. Next up, I'm planning on custom attributes, functions, etc. that a user doesn't have to use, but a more programmer-oriented user would probably enjoy having access to. But, I think I see what you're saying about a sequence diagram and that would only be a partial answer. I'll have to give that more thought!
And, I'm not wedded to the "no multi-line statements". That's more a philosophy of the super early versions of keeping it simple. I noticed some of the playground examples could already benefit from even simple line continuation. The philosophy there would be, if people don't like line continuation, they don't have to use it, but for those who want it, give them a convenient way to do it. Good point about the forward slash char... so much food for thought. Really appreciate the thoughtful comment.
Frankly for all it's issues, plantUML has been the most customizable and flexible for me. Mermaid is fine for diagrams where you don't need to customize the look and feel much; it starts to become a pain once you need to. I just wish Obsidian had as a good a support for plantUML as it does for Mermaid.
I kinda agree, and I mostly switched to mermaid because of availability. Plantuml is much more annoying to setup, and doesn't render natively on GitHub (last I checked, anyway), so if I writing anything more collaborative, mermaid requires a lot less explanation or help with setup.
And for me, one mediocre tool that works everywhere for everything beats a better tool that requires me to context switch too often, so I mostly retired Plantuml. Not happy about, but alas.
Cool, I think there's a bug when switching themes in the web ui in Safari, the artifacts example with the dark red background isn't readable in light themes. Vesper would be a nice theme to add.
I like it, drawing stuff around can get tedious if an engine like this can do it "automatically" when adding more stuff instead of copy-paste-move.
As a compiler writer I'm pondering if it'd be possible to parametrise to a degree with data-sources or you think that's something better suited to custom script generators (right now, it feels like you want to write a lot of this manually, but the grouping system does lend itself to wildcard expansions from data.
That's an interesting idea. I already have planned for some programmer-like features (functions, custom attributes, variables). However, what you're talking about seems like maybe it would want to take in an outside file (e.g., CSV, JSON) and say "loop over every entity in add as a child in this container", that sort of thing?
Am I getting that right? Super curious, because that sounds cool.
Exactly, like a server map f.ex., would be neat to have it rendered from a dataset or when developing you often have the ability to spit out CSV,JSON,etc.
It's a great starting point and I can see functions,etc being useful for other purposes so I think there's a tightrope to be walked in the design to be extensible but not get bogged down early either (if a function can result in an enumeration, you don't need a specific CSV/JSON syntax if it's just the result of a function.. but that adds other complciations naturally).
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've been playing with pikchr quite a bit and it has containers and you can specify links relative to the container. I can picture (pun not intended) your counter-example
Great question, I had to noodle that one over a bit, but I think it helped me clarify that difference between pikchr and reladraw. My container example was a poor one, and you are right that pikchr can handle adding elements to a container without fiddling.
My main objection to pikchr is that it is turtle graphics plus coordinate offsets, which to me feels like the wrong tool when I want to say "I have A to the left, and B, C, and D all right of A". I don't want to have to translate that to turtle graphic movements like saying "there's a group, draw B, move down some amount, place C, move down again, place D".
Similarly, if I'm thinking at the level of abstraction of nodes and edges and relative positions, it feels awkward to say something like this in pikchr (where the 0.2 is a guess to fiddle with):
arrow from Web.s down 0.2 then right until even with DB.s then to DB.s
Rather than saying in reladraw:
edge web -> db from: bottom to: bottom
I think it's less a matter of "reladraw can do it, but pikchr cannot". It's more like, "both can get to the same destination, but how you get there is a matter of taste and how you express your intent".
For example in pikchr:
A: box "A" fit
G: [
down
B: box "B" fit
move 0.1
C: box "C" fit
move 0.1
D: box "D" fit
move 0.1
E: box "E" fit
] with .w at A.e+(0.5,0)
arrow from A to G.B chop
arrow from A to G.C chop
arrow from A to G.D chop
arrow from A to G.E chop
To me, it's not as clear that your intent is that you want several nodes right of A. However, in reladraw, it's clearer to me that the intent is "these things are right of A":
node a "A"
node b "B" right of a
node c "C" right of a
node d "D" right of a
node e "E" right of a
edge a -> b
edge a -> c
edge a -> d
edge a -> e
However, that's a subjective taste thing and I could see some people liking the pikchr approach.
Oh interesting! I plan to add custom attributes, functions, variables. I was also thinking about macros and will add your parameters for object labels in as another idea. Thanks :)
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 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.
Not by itself, but an agent using Reladraw could. The real smarts would be the agent, and Reladraw just gives it a language and tool to express itself clearly and efficiently.
You could take someone's explanation of their architecture, give it to an agent, and ask it to render it as a diagram using Graphviz, Mermaid, Draw.io, etc. The problem is that some of those don't give the agent control over what the diagram looks like (Graphviz, Mermaid) and others are inefficient and fiddly for an agent to manipulate (Draw.io). Reladraw aims to be easy for an agent (or human) to edit (like Mermaid) but have the expressiveness and positioning like you'd be able to achieve with a carefully crafted Draw.io diagram.
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! >.<'
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)
Yes this would be one way. But maybe a suite of plungins that allows other renerers to consume .rel files might make for a better ecosystem.
To explain the use case: One advantage would be: maintain model (and views) in C4, provide layout on top.
We recently generated a big C4 model of the whole company. Good and informative since you can click through it! But it doesn't look nice and doesn't tell a coherent picture visually.
This is a wonderful idea that fills a gap that has caused me much pain! When it's more stable I'll be looking for (or creating) an Obsidian plugin, a VS Code extension, etc.
Opening reladraw/docs/index.html to make a diagram then copy-pasting to save it is a little cumbersome.
this looks awesome! A very naive question, because I never bothered to learn how it works, but can I embed this in markdown files with ```reladraw, as I can do with ```mermaid? Mermaid gets rendered inside markdown files, in both IntelliJ and Github. I assume both added support for it at some point. But I don't know the mechanics of how this works. I wouldn't be able to use this until then, unfortunately.
Thanks :) A great question. So, I believe Github simply built in support for Mermaid as just something they natively support. That means getting reladraw to "just work" in Github markdown files is sorta not possible. The workaround is rendering to SVG and linking to the SVG (obviously not nearly as convenient).
For tools like IntelliJ, VSCode, Obsidian, they would be easier to get working I think, as they all support plugins/extensions. That way, they'd know what to do when they encounter a fenced-in area starting with ```reladraw.
Yea, I felt the same. I started with Graphviz (dot language) and had fun playing with it, but ended up always back to something like Draw.io, because I couldn't get things positioned how I wanted.
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.
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!
I tried scriptc. Unfortunately, it doesn't work with this code at present (e.g., maps keyed by object and a number of various things). However, thanks for suggesting it. I have a note to revisit at some point.
Another option that appears to work well is to use Deno. I tried on my machine and it worked great. Only downside is the executable size is beefy. Could be about 70-105MB, or roughly 30MB compressed.
I don't know if that still sounds attractive? A 30MB download from Github, and then uncompressed to 100MB, and no other dependencies? (Most of it would be the Deno runtime, with only about 300KB being Reladraw)
That's a cool idea. I'll add it to my todo list. Going from reladraw -> drawio is probably the easier direction. drawio -> reladraw is probably the more challenging piece, because it would have to convert absolute positions into the relative positions it thinks you intended. It could just make a best effort along with some simplifying assumptions.
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.
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.
There's a similarity, but they differ in how you say what you want. pic is turtle graphics with explicit placement with coords and offsets as needed. reladraw is all about relationships (and not having to specify coordinates/offsets/distances).
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.
That's something I'm trying to keep in mind for sure. If someone said something that couldn't be rendered, instead of surprising you with the tool deciding for you, that might be where the error comes in rather than a warning. The trivial example would be you said B is both "left of A" and "right of A".
But, I could see the other extreme where if you said "I want an edge going from the left side of A to the right side of B", you wouldn't want the tool to say "well, you didn't specify if I should go above A or below A, so I refuse to do anything". That could be super annoying. A sensible default that you can override would probably be more ergonomic there.
Is that sorta the way you'd think about it too? Or would you be more in favor of greater permissiveness, where the tool prefers warning even in contradictory scenarios?
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!
Won’t it be a good idea to stay at the visual level?
Instead of generating visuals from text and then back to text, just communicate visually with your agents.
Something like UML provides a certain granularity to be able to code something usefully in pure visual language. Of course there are other visual programming languages that provide more depth and would probably be better suited.
Point remains that a solution based on constantly mapping better two different representations of the same thing won’t be a long term efficient solution.
For my part, I've found Literate Programming to be the best lever on this for my own work, and there has been some discussion of other folks being successful applying it to LLM work:
https://news.ycombinator.com/item?id=47300747
I tried most of the diagrams out there, the best thing is installing drawio skill and make it generate one for you based on your description.
Exactly! I'd like to give it a try as well!
The readme says:
> 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.
D2's layout engine TALA [1] actually allows you to provide a lot of manual control. TALA used to be commercial, but is now open source.
In my own testing, TALA tends to produce much better layouts than Mermaid, including the ELK layout algorithm (which is not Mermaid's default; D2 also supports ELK).
TALA supports controlling direction per container, defining which shapes have to be near each other, and so on. I've not played with this yet, though.
[1] https://d2lang.com/tour/tala/
Thanks for mentioning TALA. I feel like TALA does add more control than Mermaid, but in spirit sits closer to Mermaid than Reladraw. It keeps the auto layout, but with extra ways to coax the diagram into a different shape, by saying things like "keep this node pinned over here" or "keep these nodes close to one another".
For the diagrams I usually want to create, that's still not enough control to create what I envision.
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
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)
This is just for me, but I don't think I want to get into the business of specifying placement in that much detail. It would too cumbersome and I'd rather focus on what I want the diagram to convey, rather than how.
Genuine bug! Good find. I'll look into a fix.
Love it! I created a VSCode extension to render it in markdown files and highlight its syntax: https://github.com/volkanunsal/relative-diagrams-vscode/
Thanks for making that! Just a heads up, reladraw is changing super fast - I think the rendering/highlighting will work smoothly with syntax changes, the more annoying thing would be any JS API breaking changes.
No problem! I hooked up dependabot to detect upstream changes, so when you bump up the version number, it should create a PR and bump the version number of the extension, and I will merge. I think the unit tests should catch any regression.
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 :)
The README looks LLM generated. Sorry, but that's where my interaction stops
Appreciate the feedback. I gave the README a rewrite.
Now do the rest of the codebase.
Why put so much effort (checked your blog as well) into hating the new reality ?
I also want to know, and liken the pop fervor seen from some as religious in origin.
https://news.ycombinator.com/item?id=49878739 (my analogy.)
I'm guessing we're seeing actual religions appear, human effort potentially being blessed and machine being the work of Satan. It feels like those times are emerging, to me where people are inventing new religions out of fear of meaninglessness.
Strange times indeed.
why?
Why would you consider a project which appears to be fully coded by Claude worthy of a Show HN post?
Why does Claude output being shown to humans mandate it be rewritten before before consumption? What school of thought is that from?
Snark humor: We are not in The Name Of The Rose and this code is not Aristotle's forbidden second volume of Poetics which is antithetical to the teachings of Christ and is deserving to being hidden in a labyrinth by Benedictine monks.
Absolutism as a philosophy sort of supports fanaticism. Absolute Certainly could be the religion which is being formed here during this onset of AI challenging humanity's utility.
because it is useful and interesting. why should they rewrite the project without LLM input?
The best looking diagram library where you can explicitly place elements IMO is schemdraw (python). Ironically it is a library for drawing electronic circuit diagrams with some flowchart functionality on the side.
Examples: https://schemdraw.readthedocs.io/en/stable/gallery/flowchart...
Usage: https://schemdraw.readthedocs.io/en/stable/elements/flow.htm...
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!
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.
I suspect the subject line to this "Where you decide where to place things" is a step away from D2; I find that fussy in D2!
That's an interesting idea, and an unexplored design space. Graphviz's dot has rank and head/tail ports, and Plantuml's class diagram has some support for relative position, but both are more hints for the layout engine, not deterministic declarations. If I had a nickel for every hour I spent fiddling with a Plantuml diagram to get the relation directions to force the layout into at least an approximation of what I wanted, I'll be a lot closer to retirement.
I like that you're going for one generic syntax instead of many specific ones, like mermaid and Plantuml, but it's as much as a pro as it is a con, it's one reason why these languages evolved in the first place, instead of everyone just using DOT. One possible mitigation would be some sort of reuse mechanism? Some way that generic nodes could be defined once and instantiated many times, so if I wanted to draw something like a sequence diagram, I could define/change my participant lanes just once.
Another issue the "No multi-line statements, no line continuations, no blocks." philosophy. I get *why* you chose it, and has its advantages, but it's a pretty annoying constraint, specially if one wants to have longer node names, or have more detailed description of the node in its label, like listing the responsibilities of a class, for instance. "No blocks" is something that can probably won't make much difference, but line continuations (i.e., some distinction between physical and logical lines) can make or break the user experience, IMHO
The syntax for line breaks is another thing I urge you to reconsider, '/' is waaay to common of a character, and being forced to write long strings in a single line can get *really* annoying. Some sort of multiline string support would really make your existing syntax shine.
The last two suggestions/complaints would complicate your parser a lot, specially since you're writing it manually, so, they are trade offs, but as a user who'd love to have something like this on my toolbelt, not having these features would make me hesitate a lot on investing time in this tool.
That said, it's a nice idea, I'll keep an eye on it =)
Thanks! Some serious food for thought. Next up, I'm planning on custom attributes, functions, etc. that a user doesn't have to use, but a more programmer-oriented user would probably enjoy having access to. But, I think I see what you're saying about a sequence diagram and that would only be a partial answer. I'll have to give that more thought!
And, I'm not wedded to the "no multi-line statements". That's more a philosophy of the super early versions of keeping it simple. I noticed some of the playground examples could already benefit from even simple line continuation. The philosophy there would be, if people don't like line continuation, they don't have to use it, but for those who want it, give them a convenient way to do it. Good point about the forward slash char... so much food for thought. Really appreciate the thoughtful comment.
Frankly for all it's issues, plantUML has been the most customizable and flexible for me. Mermaid is fine for diagrams where you don't need to customize the look and feel much; it starts to become a pain once you need to. I just wish Obsidian had as a good a support for plantUML as it does for Mermaid.
I kinda agree, and I mostly switched to mermaid because of availability. Plantuml is much more annoying to setup, and doesn't render natively on GitHub (last I checked, anyway), so if I writing anything more collaborative, mermaid requires a lot less explanation or help with setup.
And for me, one mediocre tool that works everywhere for everything beats a better tool that requires me to context switch too often, so I mostly retired Plantuml. Not happy about, but alas.
Cool, I think there's a bug when switching themes in the web ui in Safari, the artifacts example with the dark red background isn't readable in light themes. Vesper would be a nice theme to add.
Yep, thanks for noticing. Definitely a bug with the themes. Now fixed. And, Vesper theme added in version 0.9.0 in npm and also in the playground :)
I like it, drawing stuff around can get tedious if an engine like this can do it "automatically" when adding more stuff instead of copy-paste-move.
As a compiler writer I'm pondering if it'd be possible to parametrise to a degree with data-sources or you think that's something better suited to custom script generators (right now, it feels like you want to write a lot of this manually, but the grouping system does lend itself to wildcard expansions from data.
That's an interesting idea. I already have planned for some programmer-like features (functions, custom attributes, variables). However, what you're talking about seems like maybe it would want to take in an outside file (e.g., CSV, JSON) and say "loop over every entity in add as a child in this container", that sort of thing?
Am I getting that right? Super curious, because that sounds cool.
Exactly, like a server map f.ex., would be neat to have it rendered from a dataset or when developing you often have the ability to spit out CSV,JSON,etc.
It's a great starting point and I can see functions,etc being useful for other purposes so I think there's a tightrope to be walked in the design to be extensible but not get bogged down early either (if a function can result in an enumeration, you don't need a specific CSV/JSON syntax if it's just the result of a function.. but that adds other complciations naturally).
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.
Can you share an example?
I've been playing with pikchr quite a bit and it has containers and you can specify links relative to the container. I can picture (pun not intended) your counter-example
Great question, I had to noodle that one over a bit, but I think it helped me clarify that difference between pikchr and reladraw. My container example was a poor one, and you are right that pikchr can handle adding elements to a container without fiddling.
My main objection to pikchr is that it is turtle graphics plus coordinate offsets, which to me feels like the wrong tool when I want to say "I have A to the left, and B, C, and D all right of A". I don't want to have to translate that to turtle graphic movements like saying "there's a group, draw B, move down some amount, place C, move down again, place D".
Similarly, if I'm thinking at the level of abstraction of nodes and edges and relative positions, it feels awkward to say something like this in pikchr (where the 0.2 is a guess to fiddle with):
Rather than saying in reladraw: I think it's less a matter of "reladraw can do it, but pikchr cannot". It's more like, "both can get to the same destination, but how you get there is a matter of taste and how you express your intent".For example in pikchr:
To me, it's not as clear that your intent is that you want several nodes right of A. However, in reladraw, it's clearer to me that the intent is "these things are right of A": However, that's a subjective taste thing and I could see some people liking the pikchr approach.This is a great example! Thank you
I think you're right that it's a matter of taste and that the intent is better represented by reladraw.
If I can point some personal downsides of pikchr is that there's no loops and when using macros you can't use parameters to create object labels.
For example, Triangle$1: line...
Just some thoughts in case you're looking for future inspiration for the language
Oh interesting! I plan to add custom attributes, functions, variables. I was also thinking about macros and will add your parameters for object labels in as another idea. Thanks :)
I’m excited to see this, but switching many of the examples from “dark” to “light” or “print” theme leaves the boxes black and the text unreadable.
Themes in the playground examples are fixed!
Thanks, I think I see what the issue is!
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 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.
OP, is this something I could use when someone is explaining their architecture and this simply can interpret their words into a diagram?
Not by itself, but an agent using Reladraw could. The real smarts would be the agent, and Reladraw just gives it a language and tool to express itself clearly and efficiently.
You could take someone's explanation of their architecture, give it to an agent, and ask it to render it as a diagram using Graphviz, Mermaid, Draw.io, etc. The problem is that some of those don't give the agent control over what the diagram looks like (Graphviz, Mermaid) and others are inefficient and fiddly for an agent to manipulate (Draw.io). Reladraw aims to be easy for an agent (or human) to edit (like Mermaid) but have the expressiveness and positioning like you'd be able to achieve with a carefully crafted Draw.io diagram.
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! >.<'
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)
Super interesting. So, you'd have something like "use architecture.dsl" (to "load" the C4 model definitions), and then begin to specify layout?
Yes this would be one way. But maybe a suite of plungins that allows other renerers to consume .rel files might make for a better ecosystem.
To explain the use case: One advantage would be: maintain model (and views) in C4, provide layout on top.
We recently generated a big C4 model of the whole company. Good and informative since you can click through it! But it doesn't look nice and doesn't tell a coherent picture visually.
This is a wonderful idea that fills a gap that has caused me much pain! When it's more stable I'll be looking for (or creating) an Obsidian plugin, a VS Code extension, etc.
Opening reladraw/docs/index.html to make a diagram then copy-pasting to save it is a little cumbersome.
Thanks very much. And, I totally agree. The workflow at present without these quality of life features is a bit rough around the edges :)
I'll use it next week for a diagram I've been trying to create for work and I'll let you know if I run into anything it can't handle.
You stole my planned project for next weekend! I was actually planning on doing something very similar to this.
I'm glad you beat me to this; I think what you made is likely better than what I would have produced.
Thanks very much! If you have ideas or feature requests, let me know!
this looks awesome! A very naive question, because I never bothered to learn how it works, but can I embed this in markdown files with ```reladraw, as I can do with ```mermaid? Mermaid gets rendered inside markdown files, in both IntelliJ and Github. I assume both added support for it at some point. But I don't know the mechanics of how this works. I wouldn't be able to use this until then, unfortunately.
Thanks :) A great question. So, I believe Github simply built in support for Mermaid as just something they natively support. That means getting reladraw to "just work" in Github markdown files is sorta not possible. The workaround is rendering to SVG and linking to the SVG (obviously not nearly as convenient).
For tools like IntelliJ, VSCode, Obsidian, they would be easier to get working I think, as they all support plugins/extensions. That way, they'd know what to do when they encounter a fenced-in area starting with ```reladraw.
Awesome! Exactly the problem I was having with drawio and mermaid. Nice work on addressing these problems and sharing it!
This is an area I think I've really enjoyed AI coding: DSLs are pretty fun to make and you can get pretty creative. Bravo on this
Thanks :) It is fun to play with!
Always struggle with Graphviz tweaking my carefully planned positions. Explicit control here looks like a godsend.
Yea, I felt the same. I started with Graphviz (dot language) and had fun playing with it, but ended up always back to something like Draw.io, because I couldn't get things positioned how I wanted.
Just gave it a spin. Really like it. Adds a lot of visual clarity. Margins matter :) Thx!
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 :)
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.
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.
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!
Well done, I was struggling with this exact problem last week.
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
I tried scriptc. Unfortunately, it doesn't work with this code at present (e.g., maps keyed by object and a number of various things). However, thanks for suggesting it. I have a note to revisit at some point.
Another option that appears to work well is to use Deno. I tried on my machine and it worked great. Only downside is the executable size is beefy. Could be about 70-105MB, or roughly 30MB compressed.
I don't know if that still sounds attractive? A 30MB download from Github, and then uncompressed to 100MB, and no other dependencies? (Most of it would be the Deno runtime, with only about 300KB being Reladraw)
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.
Add a way to convert drawio into this or generate it from drawio
That's a cool idea. I'll add it to my todo list. Going from reladraw -> drawio is probably the easier direction. drawio -> reladraw is probably the more challenging piece, because it would have to convert absolute positions into the relative positions it thinks you intended. It could just make a best effort along with some simplifying assumptions.
I always wanted this kind of tool, it’s a great idea
Nice to see tools improving human-agent collaboration.
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.
great work. but at this point prompting a frontier model to make a svg diagram works so well..
I use Excalidraw for this
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.
Updated! Edges can now have right angles (sharp or rounded). And, I added in more edge customization, like solid/dashed/dotted and thickness.
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!
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.
wow this is amazing!
So, like pic?
There's a similarity, but they differ in how you say what you want. pic is turtle graphics with explicit placement with coords and offsets as needed. reladraw is all about relationships (and not having to specify coordinates/offsets/distances).
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.
>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 think this should be a warning. Fighting the compiler when trying to draw a diagram is maybe a bit too much...
That's something I'm trying to keep in mind for sure. If someone said something that couldn't be rendered, instead of surprising you with the tool deciding for you, that might be where the error comes in rather than a warning. The trivial example would be you said B is both "left of A" and "right of A".
But, I could see the other extreme where if you said "I want an edge going from the left side of A to the right side of B", you wouldn't want the tool to say "well, you didn't specify if I should go above A or below A, so I refuse to do anything". That could be super annoying. A sensible default that you can override would probably be more ergonomic there.
Is that sorta the way you'd think about it too? Or would you be more in favor of greater permissiveness, where the tool prefers warning even in contradictory scenarios?
[dead]
[dead]
[dead]
[dead]