Thanks for sharing, looks really nice. Way less verbose and more intuitive syntax than PlantUML. Also seems to drop some vestigial UML aspects, like those default icons in the top right of PlantUML boxes (although I don't really grok UML). Title is somewhat ambiguous, since PlantUML is open source as well.
I have a standing Google alert for UML threads, because I've been looking for a long while for a good resource on what makes a good diagram. Not how to make it or what to make it with; like a Tufte for diagrams... Anyway D2 seems to make it easy to make clean diagrams.
This is great, we need more tools like this -- diagrams that can be version controlled, iterated/edited on alongside the code, etc. I think there's so much room for innovation in the area of declarative diagramming.
I am working on a project where all documentation is in markdown and plantuml for precisely these reasons, and honestly I'm surprised at how seamless the transition has been from the usual world of Word docs plus ad-hoc diagramming tools (cough PowerPoint cough). Easy diffability is another big benefit.
Has anyone used this? Would this be what people would suggest if choosing a new text-based visualization tool?
I have been wanting to implement the C4 model, for something, since recently learning about it but haven’t yet. And I generally have used Visio and PowerPoint for these things.
Overall it works well. There are some rough edges though. Textual annotations do not work well and are nowhere visually pleasantly placed "near" where they should perceptually go.
After creating a somewhat complex "systems diagram" I also have a mixed feeling if the more verbose syntax compared to Mermaid actually is an advantage.
Interesting, I see in your link that it supports MathJax, which is awesome and was a question I just had before following your link. I actually needed that recently. I was using Mermaid, but I am not aware of Mermaid supporting MathJax or KaTeX.
D2 offers 3 layout engines. 1 of them we made and 2 open source ones. Each have their limitations, and "near" is a keyword that's only supported in TALA right now. (it's there in the docs you linked)
Seriously, no body do a little research before naming his public projects to see if some other public project had the same name that are you about to use ?
I'm talking about that D , aka D2, aka DLang has been using this name for a lot of years. This would create a lot of awful confusion!
Yes D2 is what current D version used to be called when D1 was still around, about 10 years ago.
D3 is the mythical version that would fix all D shortcomings, keeps being talked about when we have those long community rants, but that is about it, there is no project going on.
I don't have anything against the text to diagram tools, however as someone who has to create/tweak diagrams only 2-3 times in a month, I always find myself forgetting the syntax and needing to refer the docs for these utils.
I have since settled on just using excalidraw, with the vscode plugin it is easy to save/version the diagrams alongside my projects and embed them as ordinary image files in docs.
We link to this in the README for text-to-diagram.com, and it was a starting point for us when we were researching what's out there when designing D2. Thank you for maintaining this.
The biggest new thing since last time D2 was here is that we now have a playground for folks to easily check it out without installing: https://play.d2lang.com.
Also just to preface the top discussion points that arise when D2 is shared:
Yes, we're a for-profit company. D2 is 100% FOSS, and we make an alternative layout engine which we sell (Jetbrains model, i.e. your copy is your's forever if you've paid for 12+ months). It's a separate install, not packaged with D2, so you won't see it if you don't want it. D2 is perfectly usable without it, and integrates with multiple free open source layout engines (e.g. the one that Mermaid uses, "dagre", is D2's default).
Thanks! We actually released a couple weeks ago, and since then it's been almost 100% fixing/improving things the community's surfaced. Long list of stuff here: https://github.com/terrastruct/d2/releases.
Re fonts: that README is for contributing fonts. I'm not sure what the best solution is for custom fonts -- whether to just specify the name of a system font, a google font, point to a directory of local TTFs. Some discussion going on here: https://github.com/terrastruct/d2/discussions/132
(apologies for this hidden path. trying to strike the balance of making it findable for those who search for it while hidden to those who just want free.)
The license for the proprietary layout engine (TALA), was quoted to me as US$240 for 12 months of updates. For comparison, a personal license for IntelliJ IDEA Ultimate is US$169 (for the first year; less for subsequent years). As an active user and proponent of text-to-diagram tools, and as someone who isn't shy about paying for software (including my personal IntelliJ IDEA Ultimate license), I'm keen on buying a better layout engine, but IMO this price-point is a bit much.
Dumb question if i may, but what is the time saving with "an alternate layout engine"? Ie i don't even know what a layout engine is in this context, and how it would save me time over FOSS versions like mermaid.
I'm tempted to give it a shot, but i don't get what the paid version would actually net me. I'm toying with the Playground now, and in many (most?) cases the TALA version (which i think is the paid version?) seems identical to the Dagre version (Mermaid, i think?)
I'm also having difficulty finding where i'd even buy it. Hmm
It's not really time-saving. It's aesthetics, how much you care about the beauty and professionalism of your diagrams. All the layout engines will get the correctness right -- all the connections point to where you want em, etc. But they'll often do so in different ways.
Formatting is completely different. Each box is a picture on the left with text on the right. Text is two lines, bold text above and regular text below. this can be reproduced with HTML labels in Graphviz.
oh i see, you meant exactly that. Yeah, D2 isn't meant for reproductions of an exact image you already have. It's made for when you just want an aesthetic rendering of a mental model. See https://d2lang.com/tour/future/#layouts
I feel it is misleading to call d2 "an open-source alternative", when it is developed to support proprietary rendering engine, the diagram examples given in documentation were rendered by that engine and the reason given is that the free alternative is inferiour.
It's completely open source. The majority of users are using it with other layout engines. We put in work to make those look good and fix bugs around the integrations with those layout engines. The proprietary layout engine is a completely separate install. I also preface it in every post I do for D2 (https://news.ycombinator.com/item?id=33704381). There's nothing misleading.
> the results of rendering with free engines are not as good
Can you cite where this is stated? Dagre and ELK can produce preferable diagrams depending on conditions.
You can be mad that something isn't free for you, but again, I don't see how you could be misled, as the non-free part is stated upfront everywhere D2 pops up.
>> the results of rendering with free engines are not as good
> Can you cite where this is stated?
By the way I've just realised why your github repo does not provide the sources of the diagrams in docs - it would blow your game wide open, once users start asking why they aren't getting the results depicted. And almost no compileable examples, either
> You can be mad that something isn't free for you,
Will you please stop lying? I am not "mad" because something isn't free, but because you're misrepresenting the nature of your D2 language. It is not something that you're making available to benefit community, but a thinly disguised marketing ploy.
> but again, I don't see how you could be misled, as the non-free part is stated upfront everywhere D2 pops up.
You're right, d2-docs will be changed to render all diagrams with Dagre or ELK instead.
The docs existed before D2 was open source and we had open source layout options. Most of it already is, but there's a few that aren't, just carried over from before. Sorry about that.
> By the way I've just realised why your github repo does not provide the sources of the diagrams in docs - it would blow your game wide open, once users start asking why they aren't getting the results depicted. And almost no compileable examples, either
Not sure what you mean no compilable examples. Full source of the docs is at https://github.com/terrastruct/d2-docs including all the examples. The first example in the Github repo also had a line "Rendered with the TALA layout engine" so the source was upfront.
> Will you please stop lying? I am not "mad" because something isn't free, but because you're misrepresenting the nature of your D2 language. It is not something that you're making available to benefit community, but a thinly disguised marketing ploy.
We're running a company, we're absolutely interested in making money.
But open sourcing D2 doesn't just help us with user acquisition, it certainly also helps the community in adding another open source alternative in the text to diagram market. And it's good quality code. If we go under, someone else can pickup the torch and fork D2.
And it's incorrect to say that the free engines are not as good. They absolutely are suitable alternatives and do beat TALA in many instances. The team behind ELK is very talented and have been working on it for 10+ years. It's not even in our interest to hide the best parts of D2, or else no one would use it. I'd even go as far to say TALA won't ever beat them in all cases, especially when the structure is hierarchical. But that's ok, they all use different algorithms and that's what makes them great for their niches. TALA is specifically for software diagrams, in instances such as if you have many nested containers. We have plans to continue developing more in open-source, such as sequence diagram layouts that were added recently.
If you can quote a specific piece of text on our GitHub or website, we will change it to make it more clear that D2 is fully open source and TALA is just an optional optimization.
So far, for our diagraming needs we've used MermaidJS, embedded as code blocks into our Markdown documentation (github and mdbook for us, but support is pretty wide).
D2 seems like a nice upgrade:
- it has an even more intuitive syntax (which is really important for something used on-and-off by any individual developer).
- it seems to have better graph routing
However there are two things keeping us from trying it:
- not supported in our tools, most notably no mdbook plugin yet. I imagine this will change over time
- readability: node labels are tiny compared to nodes, meaning you have to zoom in much more and lose view of the larger structure
Re support: yeah it's a long queue we're making our way through. We have VSCode, Vim, Obsidian, about to roll out Slack, Discord, working on Github, etc. Somewhere down the line, mdbook will be on the chopping block. (community has also contributed plugins for TreeSitter and Emacs)
Re node labels. Yeah this has come up a few times now. We'll have something that addresses it in the next release. For now, you can change font-size:
Hi there, I’ve been following the Obsidian plugin development and noticed that it appears to be done but not yet listed in the Community Plugins? Is it likely to be available soon, do you know?
The PlantUML license is slightly chaotic though, it's provided under several licenses, and each bundle has subtle differences in behavior which are not spelled out.
GraphViz is perheps a little tedious to write, and takes some work to make look good (which makes me appreciate the D2 style), but is also definitely possible in my experience.
I think one advantage in GraphViz is the ability to output EPS. I use this often for embedding into PDF via XeLaTeX and Pandoc filters. I also saw that D2 offers some kind of LaTeX output, but was not able to dig into the docs there further.
It does look nifty, but without the tooling, I don't see myself replacing Mermaid anytime soon. For example, VSCode doesn't have live previews for D2 which makes it awkward to work with.
72 comments
[ 2.5 ms ] story [ 146 ms ] threadI have a standing Google alert for UML threads, because I've been looking for a long while for a good resource on what makes a good diagram. Not how to make it or what to make it with; like a Tufte for diagrams... Anyway D2 seems to make it easy to make clean diagrams.
I have been wanting to implement the C4 model, for something, since recently learning about it but haven’t yet. And I generally have used Visio and PowerPoint for these things.
https://d2lang.com/tour/text#how-do-i-position-text
After creating a somewhat complex "systems diagram" I also have a mixed feeling if the more verbose syntax compared to Mermaid actually is an advantage.
https://play.d2lang.com/?script=PJG7qsJAEIb7eYofTp0XSHFELMTa...
https://mermaid.js.org/syntax/flowchart.html
Is mairmaid plantuml or why is plantuml chosen as the comparison point?
The markdown embedding and integrated rendering in gitlab is really useful.
I'm talking about that D , aka D2, aka DLang has been using this name for a lot of years. This would create a lot of awful confusion!
D3 is the mythical version that would fix all D shortcomings, keeps being talked about when we have those long community rants, but that is about it, there is no project going on.
I have since settled on just using excalidraw, with the vscode plugin it is easy to save/version the diagrams alongside my projects and embed them as ordinary image files in docs.
The URL for PlantText returns a 404. You might want to update that to just planttext.com
The biggest new thing since last time D2 was here is that we now have a playground for folks to easily check it out without installing: https://play.d2lang.com.
Also just to preface the top discussion points that arise when D2 is shared:
> "What's the difference between this and--"
https://text-to-diagram.com. We made it. The maintainers of Mermaid themselves have contributed to it.
> "The name!"
I like this guy's reply: https://news.ycombinator.com/item?id=33704960
> Is there a proprietary aspect?
Yes, we're a for-profit company. D2 is 100% FOSS, and we make an alternative layout engine which we sell (Jetbrains model, i.e. your copy is your's forever if you've paid for 12+ months). It's a separate install, not packaged with D2, so you won't see it if you don't want it. D2 is perfectly usable without it, and integrates with multiple free open source layout engines (e.g. the one that Mermaid uses, "dagre", is D2's default).
Did I understand correctly that, in order to use custom fonts, one has to recompile the code with appropriate .tff files? It's shortly mentioned [1].
[1] https://github.com/terrastruct/d2/tree/master/d2renderers/d2...
Re fonts: that README is for contributing fonts. I'm not sure what the best solution is for custom fonts -- whether to just specify the name of a system font, a google font, point to a directory of local TTFs. Some discussion going on here: https://github.com/terrastruct/d2/discussions/132
I followed the submission link but found no details of pricing on that site.
(apologies for this hidden path. trying to strike the balance of making it findable for those who search for it while hidden to those who just want free.)
I'm tempted to give it a shot, but i don't get what the paid version would actually net me. I'm toying with the Playground now, and in many (most?) cases the TALA version (which i think is the paid version?) seems identical to the Dagre version (Mermaid, i think?)
I'm also having difficulty finding where i'd even buy it. Hmm
edit: Ah https://terrastruct.com/tala/ might have some of my answers
Eg: https://text-to-diagram.com/?example=chess&b=d2&layout_b=dag...
I have an improvement suggestion for the playground: have some pre-defined examples I can open from a menu and mess around with.
https://binaries.templates.cdn.office.net/support/templates/...
https://play.d2lang.com/?script=VJDNbqswEIX3fopZ3R34J3EuRUqr...
Formatting is completely different. Each box is a picture on the left with text on the right. Text is two lines, bold text above and regular text below. this can be reproduced with HTML labels in Graphviz.
Lines do not look similar too. They are round and not merged. It's concentrate in Graphviz. https://graphviz.org/docs/attrs/concentrate/
D2 is that fake corporate "open-source" intended to sucker programmers into tying their work into proprietary ecosystem.
Can you cite where this is stated? Dagre and ELK can produce preferable diagrams depending on conditions.
You can be mad that something isn't free for you, but again, I don't see how you could be misled, as the non-free part is stated upfront everywhere D2 pops up.
> Can you cite where this is stated?
By the way I've just realised why your github repo does not provide the sources of the diagrams in docs - it would blow your game wide open, once users start asking why they aren't getting the results depicted. And almost no compileable examples, either
> You can be mad that something isn't free for you,
Will you please stop lying? I am not "mad" because something isn't free, but because you're misrepresenting the nature of your D2 language. It is not something that you're making available to benefit community, but a thinly disguised marketing ploy.
> but again, I don't see how you could be misled, as the non-free part is stated upfront everywhere D2 pops up.
It is far from prominent on your site, for one.
The docs existed before D2 was open source and we had open source layout options. Most of it already is, but there's a few that aren't, just carried over from before. Sorry about that.
https://github.com/terrastruct/d2-docs/issues/43
> By the way I've just realised why your github repo does not provide the sources of the diagrams in docs - it would blow your game wide open, once users start asking why they aren't getting the results depicted. And almost no compileable examples, either
Not sure what you mean no compilable examples. Full source of the docs is at https://github.com/terrastruct/d2-docs including all the examples. The first example in the Github repo also had a line "Rendered with the TALA layout engine" so the source was upfront.
> Will you please stop lying? I am not "mad" because something isn't free, but because you're misrepresenting the nature of your D2 language. It is not something that you're making available to benefit community, but a thinly disguised marketing ploy.
We're running a company, we're absolutely interested in making money.
But open sourcing D2 doesn't just help us with user acquisition, it certainly also helps the community in adding another open source alternative in the text to diagram market. And it's good quality code. If we go under, someone else can pickup the torch and fork D2.
And it's incorrect to say that the free engines are not as good. They absolutely are suitable alternatives and do beat TALA in many instances. The team behind ELK is very talented and have been working on it for 10+ years. It's not even in our interest to hide the best parts of D2, or else no one would use it. I'd even go as far to say TALA won't ever beat them in all cases, especially when the structure is hierarchical. But that's ok, they all use different algorithms and that's what makes them great for their niches. TALA is specifically for software diagrams, in instances such as if you have many nested containers. We have plans to continue developing more in open-source, such as sequence diagram layouts that were added recently.
See https://d2lang.com/tour/layouts/
If you can quote a specific piece of text on our GitHub or website, we will change it to make it more clear that D2 is fully open source and TALA is just an optional optimization.
D2 seems like a nice upgrade:
- it has an even more intuitive syntax (which is really important for something used on-and-off by any individual developer).
- it seems to have better graph routing
However there are two things keeping us from trying it:
- not supported in our tools, most notably no mdbook plugin yet. I imagine this will change over time
- readability: node labels are tiny compared to nodes, meaning you have to zoom in much more and lose view of the larger structure
Re support: yeah it's a long queue we're making our way through. We have VSCode, Vim, Obsidian, about to roll out Slack, Discord, working on Github, etc. Somewhere down the line, mdbook will be on the chopping block. (community has also contributed plugins for TreeSitter and Emacs)
Re node labels. Yeah this has come up a few times now. We'll have something that addresses it in the next release. For now, you can change font-size:
https://play.d2lang.com/?script=cspPUtC1U3DMyUxOtVKo5lJQAPvX...
https://plantuml.com/download
Btw, is there a succinct comparison to GraphViz?
GraphViz is perheps a little tedious to write, and takes some work to make look good (which makes me appreciate the D2 style), but is also definitely possible in my experience.
E.g. SciPipe (https://scipipe.org) outputs pipeline diagrams in this style:
https://www.researchgate.net/profile/Samuel-Lampa/publicatio...
I'm not familiar with EPS. Will investigate, ty. https://github.com/terrastruct/d2/issues/489
GraphViz is included.
a: { b: { c: { d } } }
x: { y: { z: { z1 } } }
a.b -> x.y.z
https://play.d2lang.com/?script=SrRSqE6yUqhOtlKoTqmtreXiqrBS...