13 ms·

D2, a diagram scripting language that turns text to diagrams, is now open source

629 points by alixanderwang 4y ago

pipeline_peak 4y ago
Doesn’t html + css solve this?
- jeddy3 4y ago
  how?
  - pipeline_peak 4y ago
    By creating some sort of model to draw diagrams. https://code.tutsplus.com/tutorials/how-to-draw-a-pie-chart-and-doughnut-chart-using-javascript-and-html5-canvas--cms-27197 https://code.tutsplus.com/tutorials/how-to-draw-a-pie-chart-...
alixanderwang 4y ago
Hi HN, I'm Alex, at Terrastruct, where we've been making D2. This actually popped up on HN a couple months back, though it wasn't ready, e.g. not open source yet. It is now! We also put up a site for you to compare D2 with MermaidJS, Graphviz, and PlantUML: https://text-to-diagram.com https://text-to-diagram.com. Full disclosure, we're a for-profit company. The open-core part is that 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 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). If you want to read more about our plans for D2: https://d2lang.com/tour/future https://d2lang.com/tour/future. Hope you can check it out! It's got an easy install (and uninstall) process.
- deleted 4y ago
  [deleted]
- wg0 4y ago
  Beautiful! And then in golang. Thank you for open sourcing the core part.
- mooneater 4y ago
  20+ year fan of graphviz here, love seeing what you are doing with D2! Any examples of larger diagrams (1000+s of nodes) and how does that perform in layout?
  - alixanderwang 4y ago
    thank you! There isn't right now, we'd need to add a simpler layout algorithm for those, e.g. force-directed, radial, etc. That use case is not something D2 is trying to tackle though, we're just focused on software architecture diagrams right now, and I've yet to see one span that many nodes
    - nonrandomstring 4y ago
      Picking a set of domain specific targets and honing a tool to service that seems a good way to start building - rather than a general solver. I also love graphviz but had a project to create an app for legible quality management, and it was a headache to shoehorn some concepts into "nodes in an edge connected graph" way of thinking (ended up programatically scripting LaTeX). With so many visualisation concepts there's room for niche approaches (same in plotting; Matlab/Octave vs Gnuplot vs Pyplot vs R and so on)
      - alixanderwang 4y ago
        agreed! that reminds me, there's a company that specializes in this niche of visualizing large data: https://www.graphistry.com/ https://www.graphistry.com/ (haven't used it myself, looks well-made).
        lmeyerov 4y ago
        100% agreement, spot on observations! Indeed, we end up referring folks to cool diagramming tools all the time at Graphistry as d2/mermaid/diagrams.net are well-optimized for quick & beautiful diagram presentation tasks on manageably sized & fairly static datasets. Using Graphistry to do a quick markdown of how a 4 node cluster might work is a bit like driving a tank to pick up some milk :) Teams go to us more for gnarly investigation & splunking tasks that need a visual power tool, like looking at alert logs or big systems, so we optimize for making that scale interactive & easy. The overlap is real however, so a lot of room for teams to learn. Ex: We're the easiest graph tool for jupyter/databricks/streamlit etc teams who use dataframes, and I can imagine those tools learning from us here. In the reverse direction, our work more in terms of quickly configurable global data<>viz data bindings ("using the UI or API, bind each event's score to a hot-and-cold coloring palette and use a warning icon on all type=alert events"), but we have a ways to go to support the more manual artisinal effects of diagramming tools like Figma, where each element might have a super fancy & unique border style.
- JonChesterfield 4y ago
  Is the language described anywhere? Couldn't find an example other than the one on text-to-diagram and can't find anything beyond that. edit: guessing URL found https://d2lang.com/tour/intro/ https://d2lang.com/tour/intro/ which covers it, perhaps worth linking to there from the GitHub page edit2: ok it is linked, just above the section I was looking at: Reference A more formal reference specification is in the works.
- localhost 4y ago
  This is a great idea; my go-to approach is the "I'll use PowerPoint to do that and take a screenshot" mindset since I don't have a need for publication quality output. I really like the comparison site that you have created - it's great for learning these languages. I would love to see a plugin for Obsidian for the times where I need to add a custom drawing to my notes. It looks like there already are plugins for PlantUML[1] and graphviz[2] today. [1] https://github.com/QAMichaelPeng/obsidian-graphviz https://github.com/QAMichaelPeng/obsidian-graphviz [2] https://github.com/joethei/obsidian-plantuml https://github.com/joethei/obsidian-plantuml
  - alixanderwang 4y ago
    thanks! i don't use Obsidian personally and don't know how the plugins work, but if anyone sees this and wants to do a plugin for it, please reach out or open a Github issue and we'll support whatever API changes are needed (if any) to D2's plugin system to make integration easy. (created a Github Discussion to track. https://github.com/terrastruct/d2/discussions/138 https://github.com/terrastruct/d2/discussions/138 . if there's enough demand, we'll do it ourselves)
- bitcurious 4y ago
  Is the name inspired by d3.js?
  - alixanderwang 4y ago
    no
    - Tenal 4y ago
- jmyeet 4y ago
  This looks really interesting. It made me curious about something. As an example your tree is laid or left-to-right. The GraphViz one in comparison is top down. It’s not clear to me as a user if that’s forced or a choice (in either case). Are you able to clarify that sort of difference by either making the diagrams similarly laid out or adding a note if something isn’t possible?
  - alixanderwang 4y ago
    Good observation! Those are just defaults, we don't change the defaults for the comparisons to match (e.g. font sizes, shape dimensions, etc).
- ritzaco 4y ago
  wow thank you for the transparency - you literally answered all the questions up front that I care about re open core, for profit, killswitches, etc etc that usually take hours to find from a marketing landing page.
- billconan 4y ago
  I really want to learn the algorithms behind automatic layout engines. Are there any books on this topic?
  - alixanderwang 4y ago
    not that i know of, but there's a lot of research papers, under the topic of "graph visualization". we read a ton of these and combined and modified ideas for TALA. The folks at ELK are doing fantastic work in public as an academic team out of Germany. https://www.eclipse.org/elk/documentation/algorithmdevelopers.html https://www.eclipse.org/elk/documentation/algorithmdeveloper... https://www.rtsys.informatik.uni-kiel.de/en/team/soren-domros https://www.rtsys.informatik.uni-kiel.de/en/team/soren-domro... Graphviz's papers are also must-reads (for hierarchical layouts): https://graphviz.org/theory/ https://graphviz.org/theory/ In general they are surprisingly readable even without an academic background. Sometimes they go into proofs of correctness like method X really results in minimal edge crossings, and those are gnarly math, but skippable. The bad part is that a lot of these research papers have code that's just broken or wrong, or is NP-hard.
    - ejuliobatista2 4y ago
      There is this open book https://cs.brown.edu/people/rtamassi/gdhandbook/ https://cs.brown.edu/people/rtamassi/gdhandbook/ We've drawn some inspiration from there and followed to some references too
  - escot 4y ago
    dagrejs has a section on "Recommended Reading" which lists which algorithms from which papers they implement. https://github.com/dagrejs/dagre/wiki#recommended-reading https://github.com/dagrejs/dagre/wiki#recommended-reading
- trey-jones 4y ago
  I'm excited to see this. It's the first repository I've starred in a long time. I'm asked for these types of diagrams from time to time and I've bounced between many different tools, none of which I've found to be satisfactory. I will try this next. Thank you for your work on it.
- laomai 4y ago
  Looks awesome! Very easy to read! Can't wait for an Obsidian plugin! :D
- linuxdude314 4y ago
  Do you maintain a dagr fork internally? The project looks to be deprecated: https://github.com/dagrejs/dagre https://github.com/dagrejs/dagre
  - alixanderwang 4y ago
    we maintain a wrapper around dagre, which adds functionality like supporting container to container connection. dagre is unmaintained, but it's also "complete", in that it implements the theoretical papers it set out to.
    - tunesmith 4y ago
      I'm wondering why you don't use elkjs? I recently moved my own side project from dagre to elkjs for exactly this reason.
      - alixanderwang 4y ago
        elkjs is an alternative! https://github.com/terrastruct/d2#plugins https://github.com/terrastruct/d2#plugins. we haven't gotten the defaults to look as good though
        tunesmith 4y ago
        ah! I understand, I've spent a little too much time playing with way too many combinations of elk's configs.
        alixanderwang 4y ago
        if you'd like to help, we're trying to figure some of these configs here in case something stands out to you! https://github.com/terrastruct/d2/pull/95 https://github.com/terrastruct/d2/pull/95
  - deleted 4y ago
    [deleted]
- Abishek_Muthian 4y ago
  Congratulations on the launch! The comparison website is neat. I don't like to draw the architectural diagrams which graphical tools for my Open-source projects, I'll try D2 for my next project.
- t0k0l0sh 4y ago
  Can you include https://diagrams.mingrammer.com/ https://diagrams.mingrammer.com/ in the comparisons? :-D
causi 4y ago
I like the idea of an OpenSCAD for diagramming. Rather surprised it didn't exist already.
- kasbah 4y ago
  It has since at least 1991 when Graphviz was first released. https://en.wikipedia.org/wiki/Graphviz https://en.wikipedia.org/wiki/Graphviz
  - tleb_ 4y ago
    An even earlier tool: Pic, which had its paper released in 1981. It belongs to the troff ecosystem of tools. I'd be interested to know about other tools from this era! Paper: https://dl.acm.org/doi/10.1145/872730.806459 https://dl.acm.org/doi/10.1145/872730.806459 Mention in troff doc: https://www.troff.org/prog.html#pic https://www.troff.org/prog.html#pic Wikipedia page: https://en.wikipedia.org/wiki/PIC_(markup_language) https://en.wikipedia.org/wiki/PIC_(markup_language)
    - blutack 4y ago
      Pikchr is a modern implementation of PIC (with some nice new features) from Sqlite/Fossil! https://pikchr.org/home/doc/trunk/homepage.md https://pikchr.org/home/doc/trunk/homepage.md
lloydatkinson 4y ago
Very cool - how does it compare to mermaid?
- taink 4y ago
  They put up a site here: https://text-to-diagram.com/ https://text-to-diagram.com/ It's buried in the FAQ but it was an interesting comparison
  - lloydatkinson 4y ago
    Wow. I thought mermaid was the future but I think I've been won over by D2. Can use markdown inside, can use code inside, and has some auto formatting tools apparently. This seems like such a better experience than literally any of the other comparisons.
- deleted 4y ago
  [deleted]
pizza234 4y ago
I've been using PlantUML and Mermaid for my own diagrams. Mermaid is quite basic; it lacks functionalities that for me were necessary; for example, direct connection between attributes of different classes. All in all, PlantUML seems superior to Mermaid, at no cost (both languages are relatively simple to learn). Mermaid is supported by Github, which may be a necessary requirement for some. On the other hand, among the many functionalities, PlantUML's JSON is unusually good looking out of the box, and if one required the diagram it outputs, it's a great feature, because it requires no syntax knowledge. Both PlantUML and Mermaid mostly produce (Mermaid more) ugly-looking diagrams (dated, to say the least). In PlantUML, this problem is compounded by the explicit lack of layout, by design. Other warts: both (PlantUML and Mermaid) languages have limited comment support - they are only supported in specific locations of the diagram declarations. D2 could be a very welcome "next gen" diagramming language. However, the devil is in the details - text-to-diagram.com show a very basic functionality, so one must carefully check the requirements. Regarding text-to-diagram.com: - there's a mistake - PlantUML does support rich text (although "rich" is a fuzzy definition) - class diagrams are an important use case, which is currently missing EDIT: clarification about the comment limitations.
- alixanderwang 4y ago
  do you have an example of the rich text for PlantUML? happy to correct i've added a TODO for the class diagrams, will be included this week. https://github.com/terrastruct/text-to-diagram-site/issues/20 https://github.com/terrastruct/text-to-diagram-site/issues/2... AFAIK they all have comments (see the "Chess" example). what is the limitation of comments you're referring to?
  - pizza234 4y ago
    This is a styling example in PlantUML: class TestClass { ""Monospaced"" <color:green>Colored } See here: https://plantuml.com/creole https://plantuml.com/creole. Regarding the comments, here's a PlantUML example: class TestClass { ""Monospaced"" ' comment not supported; displayed <color:green>Colored } class TestClass2 { ' comment supported Type varname ' comment not supported; displayed } ' comment supported foo::bar --> baz ' comment not supported; breaks diagram (!)
rvba 4y ago
Quite unfortunate name, the D2 abbreviation is used for the computer game Diablo 2. On a side note, one of the Diablo 2 creators posts here from time to time.
- Macha 4y ago
  Also Dublin 2 (postcode of Dublin city), a thai hotel chain operating in the middle east also, the video game destiny 2, a german magazine, roads in several countries, a vitamin, multiple airplanes, deuterium, a paper size, 2 sided dice and a variant of steel. I don't think anyone expects short acronyms to be globally unique
  - FeepingCreature 4y ago
    Programming language D 2.0
  - vsnf 4y ago
    Sure, many namespace collisions for D2 exit in the universe of possible meanings for the acronym, but in a computer context, and whose headline is “now open source”, it’s reasonable, expected even perhaps, to assume Diablo 2. Also, and I may be showing my age here, who refers to Destiny 2 as D2 without any context?
  - rvba 4y ago
    Not my fault they chose a non unique name for their project. I just pointed it out. Supposedly naming things is one of the problems in programming.
- thiht 4y ago
  D2 is also a French tank, that's gonna be be really confusing.
aargh_aargh 4y ago
Sorry, I'm just annoyed about the demo .gif. Why is it not a video I can watch full-screen? I want to actually see the text. Why is there a huge empty border around the window? Otherwise, the shown workflow seems nice. I'll check out the syntax to see what it brings in comparison to DOT. Thank you.
- alixanderwang 4y ago
  here ya go: https://raw.githubusercontent.com/terrastruct/d2/d320f57beff36210590774d4c20537bc54b9b9a0/docs/assets/cli.gif https://raw.githubusercontent.com/terrastruct/d2/d320f57beff... and if you want to see a fuller static text and rendering: https://text-to-diagram.com/?example=wiiu https://text-to-diagram.com/?example=wiiu
- justsomehnguy 4y ago
  Demo gif is not annoying per se, but UX is awful: not only I can't see anything on a FullHD monitor, I needed two right clicks to get to the actual .gif, I still needed to go to a fullscreen view to see the text, it is still ends too soon and I have no way to pause/stop the playback. I saw a no border version (why was it recorded with a border in the first place?), but still the left part could be easily half the size, it would integrate nicely in the GH page. If you increase the notes font than it would be (probably) legible even on GH. I think it's a classical example of 'works for me'. But anyway, is there are plans for Win* release?
  - alixanderwang 4y ago
    > is there are plans for Win* release? yep. should be in a week or so, along with other installation stuff: https://github.com/terrastruct/d2/blob/master/docs/INSTALL.md#coming-soon https://github.com/terrastruct/d2/blob/master/docs/INSTALL.m...
- adrianmonk 4y ago
  > a video I can watch full-screen Plus controls. This is a separate rant, but for incomprehensible reasons, Chrome removed the ability to even enable controls for animated GIFs. So if I miss some detail I was interested in, I can't rewind. I have to wait for it to loop around again. And when it does come back up, I can't pause there; instead, I have to frantically try to memorize what I saw. Also, I don't know the length, so I don't know if it's worth my time investment to wait for it to loop.
darkteflon 4y ago
Really like the syntax - I find it much more intuitive than Mermaid. Going to give this a try. VS Code extension, too: https://github.com/terrastruct/d2-vscode https://github.com/terrastruct/d2-vscode
blutack 4y ago
I recently discovered Pikchr from Sqlite/Fossil [0] if anyone is looking for something in a similar vein, although it has it's own scripting/layout language rather than using go (a plus IMO, as it's not tied to a specific ecosystem). It's fantastic for making diagrams when you want more control over the layout than graphviz or mermaidjs but are looking for a similar type of tool. It's also clean C so easy to embed, and there's a WASM build for browser use. It is fairly simple in any general purpose language to output pikchr code - I've done this previously for producing autogenerated packet diagrams in documentation. 0: https://pikchr.org/home/doc/trunk/homepage.md https://pikchr.org/home/doc/trunk/homepage.md
- mehmd2002h 4y ago
- zellyn 4y ago
  I am a huge fan of Pikchr. I ported it to Go, and integrated it with Hugo, for my blog. I need to get back to fixing it though — a big reorganization commit in either Hugo or Goldmark made it stop working You can see the results at https://zellyn.com/2022/02/cs-ramble/ https://zellyn.com/2022/02/cs-ramble/
  - blutack 4y ago
    That's some serious Pikchr-Fu! Nice that you kept the diagrams clickable to see the code.
deleted 4y ago
[deleted]
arriu 4y ago
I got excited that the title was for the D2 game. Cool project nonetheless
GnarfGnarf 4y ago
I would love to see this as a plugin for an IDE like Visual Studio or Qt Creator. The diagram commands would be in comments, and the graphic representation rendered in-line with the source code.
- alixanderwang 4y ago
  you can do this in VSCode now actually. the CLI has a live-reloader, so if you put the PNG on a side by side window with the code, every code change will see the PNG change.
  - GnarfGnarf 4y ago
    Do you mean the PNG is automatically re-generated if the commands to describe the chart or graphic, are changed?
    - alixanderwang 4y ago
      yes
- deleted 4y ago
  [deleted]
  - g_ali 4y ago
- deleted 4y ago
  [deleted]
- nhooyr 4y ago
  noted for the VS Code plugin: https://github.com/terrastruct/d2-vscode/issues/8 https://github.com/terrastruct/d2-vscode/issues/8
  - GnarfGnarf 4y ago
andruby 4y ago
I like it and the comparison site on https://text-to-diagram.com https://text-to-diagram.com I just wanted to drop a reference to Burnt Sushi's ERD tool [0]. It only does one diagram type: Entity Relationship Diagram. It's wonderful. Human-first syntax, code comments, and some simple formatting settings like colors and font sizes that help make more complex diagram pleasing and informative. [0] https://github.com/BurntSushi/erd https://github.com/BurntSushi/erd
- adammarples 4y ago
  In theory could ERD be quite easily extended to use D2 as another renderer? It looks very simple with one render.hs file which uses Graphviz but that could be parametrized.
- alixanderwang 4y ago
  ERDs in TALA are about to get exact-column matching in its connections in the next release. e.g.: https://imgur.com/a/UUb2RfA https://imgur.com/a/UUb2RfA
mehmd2002h 4y ago
davidkunz 4y ago
Great! I was looking forward to this as a nice-looking alternative to Mermaid etc. Thanks for open-sourcing your core! I really like the cheat sheet: https://github.com/terrastruct/d2/blob/master/docs/assets/cheat_sheet.pdf https://github.com/terrastruct/d2/blob/master/docs/assets/ch...
Garlef 4y ago
What would be a reasonable way to bring the diagrams to a frontend and make them interactive? Not in the sense of editing the diagrams but rather attaching onClick handlers to nodes, or displaying metadata when hovering over a node or edge?
- alixanderwang 4y ago
  interactive tooltips are a wip, but to the larger point, D2 has a plugin system which enables extensions like this (https://github.com/terrastruct/d2/pull/91 https://github.com/terrastruct/d2/pull/91). there's still some fleshing out to do with the API, but once it's up, it should be a straightforward plugin for custom handlers. made an issue to track: https://github.com/terrastruct/d2/issues/134 https://github.com/terrastruct/d2/issues/134
  - alixanderwang 4y ago
    Actually, we'll give each node ID the ID you specify, and then you can just target it after render with DOM selectors. That should be the easiest way!
- nhooyr 4y ago
  To further elaborate, the output is an SVG so you can embed it into your DOM and then add make it interactive like any other part of the DOM. Though until we set each svg node's ID to its D2 ID, you'll have to add event handlers by selecting on value.
ohmahjong 4y ago
When it comes to generating diagrams that look nice from just about any diagram scripting language, I tend to go to "Kroki!". Hopefully they'll do some work to support D2 as well, although going from D2 -> PlantUML is something you can do in the meantime. * https://kroki.io/ https://kroki.io/
- alixanderwang 4y ago
  the creator of kroki is on it! https://github.com/yuzutech/kroki/issues/1323 https://github.com/yuzutech/kroki/issues/1323
napier 4y ago
This, but with a NLP/GPT interface for code generation.
shoelessone 4y ago
This looks great, but sequence diagrams are one of the things I use most with PlantUML. Most commonly I find these super useful to document various caching scenarios, and I use them all the time to help explain payment processing flows. https://text-to-diagram.com/ https://text-to-diagram.com/ says the sequence diagrams aren't supported, but your github description says > D2 intends to integrate with a variety of layout engines, e.g. dot, as well as single-purpose layout types like sequence diagrams. You can choose whichever layout engine you like and works best for the diagram you're making. Can you explain a bit more about this, if I wanted to create a sequence diagram with D2 today is there a simple path to follow to do this? Thanks for the work on the project!
- alixanderwang 4y ago
  that's not contradictory. we plan to do this in the next month or so, but text-to-diagram reflects current state, so it'll say it's not supported until it's publicly released. if this is a blocker, feel free to watch this issue to be notified! https://github.com/terrastruct/d2/issues/99 https://github.com/terrastruct/d2/issues/99
CubsFan1060 4y ago
Is there any way to choose if the arrows overlap other objects? Through certain configurations, the arrows will end up going directly through unrelated objects. A crappy example here. The line from x -> cont3.y goes through the cont2 container: x -> cont.y -> z x -> cont2.y x -> cont3.y cont { x -> y -> z } cont2 { x -> y -> z } cont3 { x -> y -> z }
- alixanderwang 4y ago
  interesting, what layout engine are you running that on? different ones will have different routing algorithms
  - CubsFan1060 4y ago
    That was just the default engine.
imiric 4y ago
Looks very neat, congrats on the launch! The syntax is much friendlier than any other tool of this sort, and being programmable and extensible from Go is a great plus. I think you should add this aspect to your comparison on https://text-to-diagram.com/ https://text-to-diagram.com/ (also a nice touch!), as I don't remember this being possible with others, though I might be wrong. I'm looking forward to this having sequence diagram support, and it might just become my go-to next time. Definitely keeping an eye on this project.
LeonidBugaev 4y ago
1. Is it possible to re-use part of diagram, like require statement in PlantUML? 2. Any plans for native C4 model support, or examples how to emulate it? 3. What about layout control? By default D2 generate way nicer layout, but it is synthetic. How I can tune it, give some hints, etc?
- numbsafari 4y ago
  I have basically the same set of questions.
- alixanderwang 4y ago
  1. not currently, but it's on the roadmap! 2. with any integration, if there's enough demand, we'll do it. Once we add interactivity to diagrams, it should be trivial to emulate. However I should mention that Simon Brown (the creator of C4) has his own DSL for C4 https://github.com/structurizr/dsl https://github.com/structurizr/dsl)! We have no intention of competing with it. 3. Currently the options to tune are limited. The Terrastruct app has granular layout control via drag-and-drop, and we're working to bring some of that to native/open-source.
Existenceblinks 4y ago
Q: Anyone know any text-to-diagram that's like a hand-drawn style?
- alixanderwang 4y ago
  this is coming soon to D2: https://github.com/terrastruct/d2/pull/91 https://github.com/terrastruct/d2/pull/91
lamuswawir 4y ago
Good work. Love the simplicity.
kidsil 4y ago
This is exactly what I was looking for several months ago for describing processes in a readable and maintainable way. Basically the choices were down to: 1. Graphics tools (Google Drawings / Draw.io) - which were a pain for complex charts and maintenance. 2. Code-based tools such as plantUML which was mature and solid, but required Java :|
automatic6131 4y ago
This looks really interesting. I hope a Windows installer is out soon
- jmartrican 4y ago
  +1 for Windows installer. In case the authors are reading this.
  - alixanderwang 4y ago
    we'll get this up next week. https://github.com/terrastruct/d2/issues/96 https://github.com/terrastruct/d2/issues/96
WalterBright 4y ago
There was a popular program in the 1970s that turned Fortran into flowcharts. The flowcharts were useless, but the program was created due to some government requirement that Fortran code be accompanied by flowchats.
j_m_b 4y ago
I use Graphviz to create Entity Relationship (ER) diagrams for my database schemas. One pain point with graphviz is that once the database table schema becomes large (> 10-15 tables), the layout of the tables becomes awkward. There are times when I would like to move tables to have less overlap of relationship arrows, but this is difficult. Does D2 allow for better control of object placement in the output graph?
- alixanderwang 4y ago
  Not in the core language currently. You can do it on the Terrastruct web app (dragging things around after render). We're thinking about ways to better specify exact positioning in D2 CLI, perhaps something like a flag to lock in x,y coordinates that can be changed post-render.
pedrovhb 4y ago
This looks pretty great, though I'm surprised at the filesize for a simple diagram - 333kb from a simple test I made. A cat of the SVG prints out some base64 which I didn't try decoding, but I'd assume it's the bundled font that takes up most of the space? It'd be nice if it contained only the characters necessary for the diagram itself.
- alixanderwang 4y ago
  yeah there's overhead with the fonts bundled in. we might change this, https://github.com/terrastruct/d2/discussions/132 https://github.com/terrastruct/d2/discussions/132 i wasn't aware you could selectively choose characters for fonts, but that'd be ideal
  - andix 4y ago
    Maybe don’t bundle the font by default? Can‘t you just use the standard system fonts like tailwind does, and gives quite good results? font-family: ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, "Noto Sans", sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji";
undershirt 4y ago
Thanks for the excellent example diagram in the readme. It actually seems like the best way to understand the cheating scandal.
sgt 4y ago
Getting this on macOS after installing dyld: cannot load 'd2' (load command 0x80000033 is unknown) Abort trap: 6
- nhooyr 4y ago
  What version of macOS are you using? We built on macOS 13.0 with go1.19.3. If you're subsantially older, you'll probably have to install from source due to the c dependencies. See https://github.com/terrastruct/d2/blob/master/docs/INSTALL.md https://github.com/terrastruct/d2/blob/master/docs/INSTALL.m...
  - sgt 4y ago
    Using 10.14.6 (Mojave). I was running go 1.17 so the build didn't work at first. With go1.19 it worked and I am now running the d2 software.
pyrolistical 4y ago
Love the layout this generates, but a killer feature of mermaidjs/plantuml is it works in the browser with the document embedded in the url: https://mermaid.live/edit#pako:eNpVkEFrwzAMhf-K0GmD5A_kMFiTrpeODdbTkhxErNams2Uch1GS_Pc5yQqbTkLvew_xRuxEMRZ4CeQ1nKrGQZrnutTB9NFS30KeP00HjmDF8W2C3cNBoNfivXGXx43fLRCU43HBGKI27jpvUrn63xxPUNVH8lF8-1c5fcsE-9q86xT_X9GBk-ulPlNxpryjACWFFjO0HCwZld4eF0ODUbPlBou0KgrXBhs3J27wiiLvlYkSMGV89ZwhDVE-bq7DIoaB71BlKFVg70dePa9bN2tFGXpynyL2N2j-AZw1ZnM https://mermaid.live/edit#pako:eNpVkEFrwzAMhf-K0GmD5A_kMFiTr... https://www.planttext.com/?text=SoWkIImgAStDuU9ooazIqBLJSCp9J4wrKl18pSd9L-JYSaZDIm5A0m00 https://www.planttext.com/?text=SoWkIImgAStDuU9ooazIqBLJSCp9...
- alixanderwang 4y ago
  love this idea. https://github.com/terrastruct/d2/issues/153 https://github.com/terrastruct/d2/issues/153
hammeiam 4y ago
Is it possible to integrate this with a library like networkx? D2 has great layouts and seems very simple to create ad-hoc graphs, but it would also be nice to support graph data structures that you can slice up how you want, like this https://github.com/hammeiam/saddle-data-graph/blob/master/Saddle%20Data%20Graph.ipynb https://github.com/hammeiam/saddle-data-graph/blob/master/Sa...
- alixanderwang 4y ago
  D2 has an AST API, so you should be able to transpile from other graph libraries easily. see the second half of https://github.com/terrastruct/d2#d2-as-a-library https://github.com/terrastruct/d2#d2-as-a-library
dang 4y ago
D2: A new declarative language to turn text into diagrams - https://news.ycombinator.com/item?id=32652291 https://news.ycombinator.com/item?id=32652291 - Aug 2022 (126 comments)
- alixanderwang 4y ago
  Hi dang, that post wasn't posted by me and it was a premature release, where the top comments questioned why it's not open source. the original title for this was that it's now open source. hopefully it's not counted as a repost, perhaps the title could be reverted to its original to avoid any potential penalty of dupe? related: https://news.ycombinator.com/item?id=32656873 https://news.ycombinator.com/item?id=32656873
  - dang 4y ago
    Ok, I've put open source back in the title.
    - alixanderwang 4y ago
      thanks
xbar 4y ago
Charming example.
darkteflon 4y ago
Just looking at the documentation on themes (https://d2lang.com/tour/themes https://d2lang.com/tour/themes) - the themes themselves are great but I can't see any way to set a dark (or alternate color) background?
- alixanderwang 4y ago
  ty for the suggestion, our designer will come up with some! https://github.com/terrastruct/d2/issues/158 https://github.com/terrastruct/d2/issues/158
  - darkteflon 4y ago
    Wonderful - thank you!
kowlo 4y ago
I use Blockdiag - how come I never see it mentioned?
spacey 4y ago
This looks like a nice and modern improvement to PlantUML. Are there any plans for an IntelliJ plugin?
- alixanderwang 4y ago
  thank you! not currently
dave333 4y ago
Would love to try this out but I am having various problems with curl mostly certificates that is stopping the install. Install.sh is a bit complex for tweaking. Is there a zip or .msi or .exe I can grab to install this on Windows 10?
- nhooyr 4y ago
  For windows you'll have to build from source for now as we don't have prebuilt releases. install.sh cannot run on windows anyway afaik unless windows now has a POSIX shell interpreter? We're likely going to add a chocolatey package too. See https://github.com/terrastruct/d2/issues/96 https://github.com/terrastruct/d2/issues/96 See https://github.com/terrastruct/d2/blob/master/docs/INSTALL.md#from-source https://github.com/terrastruct/d2/blob/master/docs/INSTALL.m...
  - dave333 4y ago
    I was hoping it would work under git bash.
    - nhooyr 4y ago
      Oh, I'll note that we should test this once we have windows releases.
euroderf 4y ago
Looks great! Since it's programmable in Go, why not go whole hog ? 1) Accept an SQL schema and automatically diagram all tables that interconnect via PK/FK references (including many-to-many). 2) Starting from main(), reflect a compiled code base (or use source files' parse results from https://pkg.go.dev/go/parser https://pkg.go.dev/go/parser) and diagram it down to some level.
- alixanderwang 4y ago
  (1) is on our roadmap! transpile from postgres-exported schema CSVs
tarasglek 4y ago
This is awesome as it resolves a lot of my graphviz complaints. However it seems to be missing graphviz concept of ports. I found ports to be very useful as an alternative to labelling edges for SQL foreign key relationships. Ports make graphs more compact and easier to read esp for tables with large numbers of foreign keys
willtemperley 4y ago
Having evaluated all the options in text-to-diagram.com, considered licenses, languages, openness, and how I might roll-my-own, I picked up a pencil and paper and drew the diagram I needed in five minutes. Progress made.
HeavyStorm 4y ago
This kind of library/program must be written in javascript. To be able to do this in the browser is very, very useful.
McUsr 4y ago
Thank you, thank you, thank you. I live well with your install.sh not beeing able to reckognize that I'm on Debian and have a slightly different layout than generic Linux. On the other hand, getting installations from outside repos into /usr/local/bin, isn't a bad choice over all. Me not beeing used to using curl, I didn't realize that the dry run parameter to go at the end of install command. I guess most people who downloads from github gets that. A line or two on how you do a dry run, with the command line fully spelled out wouldn't hurt though. Now that all the sour critique is out of the way, I want to repeat my thank you's, the comparative site was great, and so were the examples, and it came just in time! I'm going to use this for small simple diagrams, and some views of ER models, I'm not into the call graph, or drawing 1000's of nodes thing at the moment, it will probably work well for that too. My point is, that your graphs are actually simpler to define than using groff's pic macro package, or the stand-alone pic2graph utility. So. Thank you!!
- alixanderwang 4y ago
  oh hm, do you think the issue was that you're on Debian or something else (different layout that you refer to)? We'll be sure to test on a Debian machine in the future. Thank you for the feedback and kind words!
mannykoum 4y ago
Any potential integration with Latex ? not sure exactly how that would work; it would be nice to either embed d2 code in a block and make the rendering part of the latex compilation. Similar to tikz. I guess for now I can use d2 and then insert the generated svg but I would like sth closer to that holy grail of version-controlled documentation where you type and everything is magically done in one step and you store no data in the repo.
- alixanderwang 4y ago
  yes, we support markdown, so latex would just be another language tag. you can follow here and be notified when it's ready: https://github.com/terrastruct/d2/issues/135 https://github.com/terrastruct/d2/issues/135
metalliqaz 4y ago
Requires a monthly subscription fee to use. HARD PASS.

629 points by alixanderwang 4y ago

pipeline_peak 4y ago

Doesn’t html + css solve this?

jeddy3 4y ago
how?
- pipeline_peak 4y ago
  By creating some sort of model to draw diagrams. https://code.tutsplus.com/tutorials/how-to-draw-a-pie-chart-and-doughnut-chart-using-javascript-and-html5-canvas--cms-27197 https://code.tutsplus.com/tutorials/how-to-draw-a-pie-chart-...

alixanderwang 4y ago

Hi HN, I'm Alex, at Terrastruct, where we've been making D2. This actually popped up on HN a couple months back, though it wasn't ready, e.g. not open source yet. It is now! We also put up a site for you to compare D2 with MermaidJS, Graphviz, and PlantUML: https://text-to-diagram.com https://text-to-diagram.com. Full disclosure, we're a for-profit company. The open-core part is that 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 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). If you want to read more about our plans for D2: https://d2lang.com/tour/future https://d2lang.com/tour/future. Hope you can check it out! It's got an easy install (and uninstall) process.

deleted 4y ago
[deleted]
wg0 4y ago
Beautiful! And then in golang. Thank you for open sourcing the core part.
mooneater 4y ago
20+ year fan of graphviz here, love seeing what you are doing with D2! Any examples of larger diagrams (1000+s of nodes) and how does that perform in layout?
- alixanderwang 4y ago
  thank you! There isn't right now, we'd need to add a simpler layout algorithm for those, e.g. force-directed, radial, etc. That use case is not something D2 is trying to tackle though, we're just focused on software architecture diagrams right now, and I've yet to see one span that many nodes
  - nonrandomstring 4y ago
    Picking a set of domain specific targets and honing a tool to service that seems a good way to start building - rather than a general solver. I also love graphviz but had a project to create an app for legible quality management, and it was a headache to shoehorn some concepts into "nodes in an edge connected graph" way of thinking (ended up programatically scripting LaTeX). With so many visualisation concepts there's room for niche approaches (same in plotting; Matlab/Octave vs Gnuplot vs Pyplot vs R and so on)
    - alixanderwang 4y ago
      agreed! that reminds me, there's a company that specializes in this niche of visualizing large data: https://www.graphistry.com/ https://www.graphistry.com/ (haven't used it myself, looks well-made).
      - lmeyerov 4y ago
        100% agreement, spot on observations! Indeed, we end up referring folks to cool diagramming tools all the time at Graphistry as d2/mermaid/diagrams.net are well-optimized for quick & beautiful diagram presentation tasks on manageably sized & fairly static datasets. Using Graphistry to do a quick markdown of how a 4 node cluster might work is a bit like driving a tank to pick up some milk :) Teams go to us more for gnarly investigation & splunking tasks that need a visual power tool, like looking at alert logs or big systems, so we optimize for making that scale interactive & easy. The overlap is real however, so a lot of room for teams to learn. Ex: We're the easiest graph tool for jupyter/databricks/streamlit etc teams who use dataframes, and I can imagine those tools learning from us here. In the reverse direction, our work more in terms of quickly configurable global data<>viz data bindings ("using the UI or API, bind each event's score to a hot-and-cold coloring palette and use a warning icon on all type=alert events"), but we have a ways to go to support the more manual artisinal effects of diagramming tools like Figma, where each element might have a super fancy & unique border style.
JonChesterfield 4y ago
Is the language described anywhere? Couldn't find an example other than the one on text-to-diagram and can't find anything beyond that. edit: guessing URL found https://d2lang.com/tour/intro/ https://d2lang.com/tour/intro/ which covers it, perhaps worth linking to there from the GitHub page edit2: ok it is linked, just above the section I was looking at: Reference A more formal reference specification is in the works.
localhost 4y ago
This is a great idea; my go-to approach is the "I'll use PowerPoint to do that and take a screenshot" mindset since I don't have a need for publication quality output. I really like the comparison site that you have created - it's great for learning these languages. I would love to see a plugin for Obsidian for the times where I need to add a custom drawing to my notes. It looks like there already are plugins for PlantUML[1] and graphviz[2] today. [1] https://github.com/QAMichaelPeng/obsidian-graphviz https://github.com/QAMichaelPeng/obsidian-graphviz [2] https://github.com/joethei/obsidian-plantuml https://github.com/joethei/obsidian-plantuml
- alixanderwang 4y ago
  thanks! i don't use Obsidian personally and don't know how the plugins work, but if anyone sees this and wants to do a plugin for it, please reach out or open a Github issue and we'll support whatever API changes are needed (if any) to D2's plugin system to make integration easy. (created a Github Discussion to track. https://github.com/terrastruct/d2/discussions/138 https://github.com/terrastruct/d2/discussions/138 . if there's enough demand, we'll do it ourselves)
bitcurious 4y ago
Is the name inspired by d3.js?
- alixanderwang 4y ago
  no
  - Tenal 4y ago
jmyeet 4y ago
This looks really interesting. It made me curious about something. As an example your tree is laid or left-to-right. The GraphViz one in comparison is top down. It’s not clear to me as a user if that’s forced or a choice (in either case). Are you able to clarify that sort of difference by either making the diagrams similarly laid out or adding a note if something isn’t possible?
- alixanderwang 4y ago
  Good observation! Those are just defaults, we don't change the defaults for the comparisons to match (e.g. font sizes, shape dimensions, etc).
ritzaco 4y ago
wow thank you for the transparency - you literally answered all the questions up front that I care about re open core, for profit, killswitches, etc etc that usually take hours to find from a marketing landing page.
billconan 4y ago
I really want to learn the algorithms behind automatic layout engines. Are there any books on this topic?
- alixanderwang 4y ago
  not that i know of, but there's a lot of research papers, under the topic of "graph visualization". we read a ton of these and combined and modified ideas for TALA. The folks at ELK are doing fantastic work in public as an academic team out of Germany. https://www.eclipse.org/elk/documentation/algorithmdevelopers.html https://www.eclipse.org/elk/documentation/algorithmdeveloper... https://www.rtsys.informatik.uni-kiel.de/en/team/soren-domros https://www.rtsys.informatik.uni-kiel.de/en/team/soren-domro... Graphviz's papers are also must-reads (for hierarchical layouts): https://graphviz.org/theory/ https://graphviz.org/theory/ In general they are surprisingly readable even without an academic background. Sometimes they go into proofs of correctness like method X really results in minimal edge crossings, and those are gnarly math, but skippable. The bad part is that a lot of these research papers have code that's just broken or wrong, or is NP-hard.
  - ejuliobatista2 4y ago
    There is this open book https://cs.brown.edu/people/rtamassi/gdhandbook/ https://cs.brown.edu/people/rtamassi/gdhandbook/ We've drawn some inspiration from there and followed to some references too
- escot 4y ago
  dagrejs has a section on "Recommended Reading" which lists which algorithms from which papers they implement. https://github.com/dagrejs/dagre/wiki#recommended-reading https://github.com/dagrejs/dagre/wiki#recommended-reading
trey-jones 4y ago
I'm excited to see this. It's the first repository I've starred in a long time. I'm asked for these types of diagrams from time to time and I've bounced between many different tools, none of which I've found to be satisfactory. I will try this next. Thank you for your work on it.
laomai 4y ago
Looks awesome! Very easy to read! Can't wait for an Obsidian plugin! :D
linuxdude314 4y ago
Do you maintain a dagr fork internally? The project looks to be deprecated: https://github.com/dagrejs/dagre https://github.com/dagrejs/dagre
- alixanderwang 4y ago
  we maintain a wrapper around dagre, which adds functionality like supporting container to container connection. dagre is unmaintained, but it's also "complete", in that it implements the theoretical papers it set out to.
  - tunesmith 4y ago
    I'm wondering why you don't use elkjs? I recently moved my own side project from dagre to elkjs for exactly this reason.
    - alixanderwang 4y ago
      elkjs is an alternative! https://github.com/terrastruct/d2#plugins https://github.com/terrastruct/d2#plugins. we haven't gotten the defaults to look as good though
      - tunesmith 4y ago
        ah! I understand, I've spent a little too much time playing with way too many combinations of elk's configs.
        alixanderwang 4y ago
        if you'd like to help, we're trying to figure some of these configs here in case something stands out to you! https://github.com/terrastruct/d2/pull/95 https://github.com/terrastruct/d2/pull/95
- deleted 4y ago
  [deleted]
Abishek_Muthian 4y ago
Congratulations on the launch! The comparison website is neat. I don't like to draw the architectural diagrams which graphical tools for my Open-source projects, I'll try D2 for my next project.
t0k0l0sh 4y ago
Can you include https://diagrams.mingrammer.com/ https://diagrams.mingrammer.com/ in the comparisons? :-D

causi 4y ago

I like the idea of an OpenSCAD for diagramming. Rather surprised it didn't exist already.

kasbah 4y ago
It has since at least 1991 when Graphviz was first released. https://en.wikipedia.org/wiki/Graphviz https://en.wikipedia.org/wiki/Graphviz
- tleb_ 4y ago
  An even earlier tool: Pic, which had its paper released in 1981. It belongs to the troff ecosystem of tools. I'd be interested to know about other tools from this era! Paper: https://dl.acm.org/doi/10.1145/872730.806459 https://dl.acm.org/doi/10.1145/872730.806459 Mention in troff doc: https://www.troff.org/prog.html#pic https://www.troff.org/prog.html#pic Wikipedia page: https://en.wikipedia.org/wiki/PIC_(markup_language) https://en.wikipedia.org/wiki/PIC_(markup_language)
  - blutack 4y ago
    Pikchr is a modern implementation of PIC (with some nice new features) from Sqlite/Fossil! https://pikchr.org/home/doc/trunk/homepage.md https://pikchr.org/home/doc/trunk/homepage.md

lloydatkinson 4y ago

Very cool - how does it compare to mermaid?

taink 4y ago
They put up a site here: https://text-to-diagram.com/ https://text-to-diagram.com/ It's buried in the FAQ but it was an interesting comparison
- lloydatkinson 4y ago
  Wow. I thought mermaid was the future but I think I've been won over by D2. Can use markdown inside, can use code inside, and has some auto formatting tools apparently. This seems like such a better experience than literally any of the other comparisons.
deleted 4y ago
[deleted]

pizza234 4y ago

I've been using PlantUML and Mermaid for my own diagrams. Mermaid is quite basic; it lacks functionalities that for me were necessary; for example, direct connection between attributes of different classes. All in all, PlantUML seems superior to Mermaid, at no cost (both languages are relatively simple to learn). Mermaid is supported by Github, which may be a necessary requirement for some. On the other hand, among the many functionalities, PlantUML's JSON is unusually good looking out of the box, and if one required the diagram it outputs, it's a great feature, because it requires no syntax knowledge. Both PlantUML and Mermaid mostly produce (Mermaid more) ugly-looking diagrams (dated, to say the least). In PlantUML, this problem is compounded by the explicit lack of layout, by design. Other warts: both (PlantUML and Mermaid) languages have limited comment support - they are only supported in specific locations of the diagram declarations. D2 could be a very welcome "next gen" diagramming language. However, the devil is in the details - text-to-diagram.com show a very basic functionality, so one must carefully check the requirements. Regarding text-to-diagram.com: - there's a mistake - PlantUML does support rich text (although "rich" is a fuzzy definition) - class diagrams are an important use case, which is currently missing EDIT: clarification about the comment limitations.

alixanderwang 4y ago
do you have an example of the rich text for PlantUML? happy to correct i've added a TODO for the class diagrams, will be included this week. https://github.com/terrastruct/text-to-diagram-site/issues/20 https://github.com/terrastruct/text-to-diagram-site/issues/2... AFAIK they all have comments (see the "Chess" example). what is the limitation of comments you're referring to?
- pizza234 4y ago
  This is a styling example in PlantUML: class TestClass { ""Monospaced"" <color:green>Colored } See here: https://plantuml.com/creole https://plantuml.com/creole. Regarding the comments, here's a PlantUML example: class TestClass { ""Monospaced"" ' comment not supported; displayed <color:green>Colored } class TestClass2 { ' comment supported Type varname ' comment not supported; displayed } ' comment supported foo::bar --> baz ' comment not supported; breaks diagram (!)

rvba 4y ago

Quite unfortunate name, the D2 abbreviation is used for the computer game Diablo 2. On a side note, one of the Diablo 2 creators posts here from time to time.

Macha 4y ago
Also Dublin 2 (postcode of Dublin city), a thai hotel chain operating in the middle east also, the video game destiny 2, a german magazine, roads in several countries, a vitamin, multiple airplanes, deuterium, a paper size, 2 sided dice and a variant of steel. I don't think anyone expects short acronyms to be globally unique
- FeepingCreature 4y ago
  Programming language D 2.0
- vsnf 4y ago
  Sure, many namespace collisions for D2 exit in the universe of possible meanings for the acronym, but in a computer context, and whose headline is “now open source”, it’s reasonable, expected even perhaps, to assume Diablo 2. Also, and I may be showing my age here, who refers to Destiny 2 as D2 without any context?
- rvba 4y ago
  Not my fault they chose a non unique name for their project. I just pointed it out. Supposedly naming things is one of the problems in programming.
thiht 4y ago
D2 is also a French tank, that's gonna be be really confusing.

aargh_aargh 4y ago

Sorry, I'm just annoyed about the demo .gif. Why is it not a video I can watch full-screen? I want to actually see the text. Why is there a huge empty border around the window? Otherwise, the shown workflow seems nice. I'll check out the syntax to see what it brings in comparison to DOT. Thank you.

alixanderwang 4y ago
here ya go: https://raw.githubusercontent.com/terrastruct/d2/d320f57beff36210590774d4c20537bc54b9b9a0/docs/assets/cli.gif https://raw.githubusercontent.com/terrastruct/d2/d320f57beff... and if you want to see a fuller static text and rendering: https://text-to-diagram.com/?example=wiiu https://text-to-diagram.com/?example=wiiu
justsomehnguy 4y ago
Demo gif is not annoying per se, but UX is awful: not only I can't see anything on a FullHD monitor, I needed two right clicks to get to the actual .gif, I still needed to go to a fullscreen view to see the text, it is still ends too soon and I have no way to pause/stop the playback. I saw a no border version (why was it recorded with a border in the first place?), but still the left part could be easily half the size, it would integrate nicely in the GH page. If you increase the notes font than it would be (probably) legible even on GH. I think it's a classical example of 'works for me'. But anyway, is there are plans for Win* release?
- alixanderwang 4y ago
  > is there are plans for Win* release? yep. should be in a week or so, along with other installation stuff: https://github.com/terrastruct/d2/blob/master/docs/INSTALL.md#coming-soon https://github.com/terrastruct/d2/blob/master/docs/INSTALL.m...
adrianmonk 4y ago
> a video I can watch full-screen Plus controls. This is a separate rant, but for incomprehensible reasons, Chrome removed the ability to even enable controls for animated GIFs. So if I miss some detail I was interested in, I can't rewind. I have to wait for it to loop around again. And when it does come back up, I can't pause there; instead, I have to frantically try to memorize what I saw. Also, I don't know the length, so I don't know if it's worth my time investment to wait for it to loop.

darkteflon 4y ago

Really like the syntax - I find it much more intuitive than Mermaid. Going to give this a try. VS Code extension, too: https://github.com/terrastruct/d2-vscode https://github.com/terrastruct/d2-vscode

blutack 4y ago

I recently discovered Pikchr from Sqlite/Fossil [0] if anyone is looking for something in a similar vein, although it has it's own scripting/layout language rather than using go (a plus IMO, as it's not tied to a specific ecosystem). It's fantastic for making diagrams when you want more control over the layout than graphviz or mermaidjs but are looking for a similar type of tool. It's also clean C so easy to embed, and there's a WASM build for browser use. It is fairly simple in any general purpose language to output pikchr code - I've done this previously for producing autogenerated packet diagrams in documentation. 0: https://pikchr.org/home/doc/trunk/homepage.md https://pikchr.org/home/doc/trunk/homepage.md

mehmd2002h 4y ago
zellyn 4y ago
I am a huge fan of Pikchr. I ported it to Go, and integrated it with Hugo, for my blog. I need to get back to fixing it though — a big reorganization commit in either Hugo or Goldmark made it stop working You can see the results at https://zellyn.com/2022/02/cs-ramble/ https://zellyn.com/2022/02/cs-ramble/
- blutack 4y ago
  That's some serious Pikchr-Fu! Nice that you kept the diagrams clickable to see the code.

deleted 4y ago

[deleted]

arriu 4y ago

I got excited that the title was for the D2 game. Cool project nonetheless

GnarfGnarf 4y ago

I would love to see this as a plugin for an IDE like Visual Studio or Qt Creator. The diagram commands would be in comments, and the graphic representation rendered in-line with the source code.

alixanderwang 4y ago
you can do this in VSCode now actually. the CLI has a live-reloader, so if you put the PNG on a side by side window with the code, every code change will see the PNG change.
- GnarfGnarf 4y ago
  Do you mean the PNG is automatically re-generated if the commands to describe the chart or graphic, are changed?
  - alixanderwang 4y ago
    yes
deleted 4y ago
[deleted]
- g_ali 4y ago
deleted 4y ago
[deleted]
nhooyr 4y ago
noted for the VS Code plugin: https://github.com/terrastruct/d2-vscode/issues/8 https://github.com/terrastruct/d2-vscode/issues/8
- GnarfGnarf 4y ago

andruby 4y ago

I like it and the comparison site on https://text-to-diagram.com https://text-to-diagram.com I just wanted to drop a reference to Burnt Sushi's ERD tool [0]. It only does one diagram type: Entity Relationship Diagram. It's wonderful. Human-first syntax, code comments, and some simple formatting settings like colors and font sizes that help make more complex diagram pleasing and informative. [0] https://github.com/BurntSushi/erd https://github.com/BurntSushi/erd

adammarples 4y ago
In theory could ERD be quite easily extended to use D2 as another renderer? It looks very simple with one render.hs file which uses Graphviz but that could be parametrized.
alixanderwang 4y ago
ERDs in TALA are about to get exact-column matching in its connections in the next release. e.g.: https://imgur.com/a/UUb2RfA https://imgur.com/a/UUb2RfA

mehmd2002h 4y ago

davidkunz 4y ago

Great! I was looking forward to this as a nice-looking alternative to Mermaid etc. Thanks for open-sourcing your core! I really like the cheat sheet: https://github.com/terrastruct/d2/blob/master/docs/assets/cheat_sheet.pdf https://github.com/terrastruct/d2/blob/master/docs/assets/ch...

Garlef 4y ago

What would be a reasonable way to bring the diagrams to a frontend and make them interactive? Not in the sense of editing the diagrams but rather attaching onClick handlers to nodes, or displaying metadata when hovering over a node or edge?

alixanderwang 4y ago
interactive tooltips are a wip, but to the larger point, D2 has a plugin system which enables extensions like this (https://github.com/terrastruct/d2/pull/91 https://github.com/terrastruct/d2/pull/91). there's still some fleshing out to do with the API, but once it's up, it should be a straightforward plugin for custom handlers. made an issue to track: https://github.com/terrastruct/d2/issues/134 https://github.com/terrastruct/d2/issues/134
- alixanderwang 4y ago
  Actually, we'll give each node ID the ID you specify, and then you can just target it after render with DOM selectors. That should be the easiest way!
nhooyr 4y ago
To further elaborate, the output is an SVG so you can embed it into your DOM and then add make it interactive like any other part of the DOM. Though until we set each svg node's ID to its D2 ID, you'll have to add event handlers by selecting on value.

ohmahjong 4y ago

When it comes to generating diagrams that look nice from just about any diagram scripting language, I tend to go to "Kroki!". Hopefully they'll do some work to support D2 as well, although going from D2 -> PlantUML is something you can do in the meantime. * https://kroki.io/ https://kroki.io/

alixanderwang 4y ago
the creator of kroki is on it! https://github.com/yuzutech/kroki/issues/1323 https://github.com/yuzutech/kroki/issues/1323

napier 4y ago

This, but with a NLP/GPT interface for code generation.

shoelessone 4y ago

This looks great, but sequence diagrams are one of the things I use most with PlantUML. Most commonly I find these super useful to document various caching scenarios, and I use them all the time to help explain payment processing flows. https://text-to-diagram.com/ https://text-to-diagram.com/ says the sequence diagrams aren't supported, but your github description says > D2 intends to integrate with a variety of layout engines, e.g. dot, as well as single-purpose layout types like sequence diagrams. You can choose whichever layout engine you like and works best for the diagram you're making. Can you explain a bit more about this, if I wanted to create a sequence diagram with D2 today is there a simple path to follow to do this? Thanks for the work on the project!

alixanderwang 4y ago
that's not contradictory. we plan to do this in the next month or so, but text-to-diagram reflects current state, so it'll say it's not supported until it's publicly released. if this is a blocker, feel free to watch this issue to be notified! https://github.com/terrastruct/d2/issues/99 https://github.com/terrastruct/d2/issues/99

CubsFan1060 4y ago

Is there any way to choose if the arrows overlap other objects? Through certain configurations, the arrows will end up going directly through unrelated objects. A crappy example here. The line from x -> cont3.y goes through the cont2 container: x -> cont.y -> z x -> cont2.y x -> cont3.y cont { x -> y -> z } cont2 { x -> y -> z } cont3 { x -> y -> z }

alixanderwang 4y ago
interesting, what layout engine are you running that on? different ones will have different routing algorithms
- CubsFan1060 4y ago
  That was just the default engine.

imiric 4y ago

Looks very neat, congrats on the launch! The syntax is much friendlier than any other tool of this sort, and being programmable and extensible from Go is a great plus. I think you should add this aspect to your comparison on https://text-to-diagram.com/ https://text-to-diagram.com/ (also a nice touch!), as I don't remember this being possible with others, though I might be wrong. I'm looking forward to this having sequence diagram support, and it might just become my go-to next time. Definitely keeping an eye on this project.

LeonidBugaev 4y ago

1. Is it possible to re-use part of diagram, like require statement in PlantUML? 2. Any plans for native C4 model support, or examples how to emulate it? 3. What about layout control? By default D2 generate way nicer layout, but it is synthetic. How I can tune it, give some hints, etc?

numbsafari 4y ago
I have basically the same set of questions.
alixanderwang 4y ago
1. not currently, but it's on the roadmap! 2. with any integration, if there's enough demand, we'll do it. Once we add interactivity to diagrams, it should be trivial to emulate. However I should mention that Simon Brown (the creator of C4) has his own DSL for C4 https://github.com/structurizr/dsl https://github.com/structurizr/dsl)! We have no intention of competing with it. 3. Currently the options to tune are limited. The Terrastruct app has granular layout control via drag-and-drop, and we're working to bring some of that to native/open-source.

Existenceblinks 4y ago

Q: Anyone know any text-to-diagram that's like a hand-drawn style?

alixanderwang 4y ago
this is coming soon to D2: https://github.com/terrastruct/d2/pull/91 https://github.com/terrastruct/d2/pull/91

lamuswawir 4y ago

Good work. Love the simplicity.

kidsil 4y ago

This is exactly what I was looking for several months ago for describing processes in a readable and maintainable way. Basically the choices were down to: 1. Graphics tools (Google Drawings / Draw.io) - which were a pain for complex charts and maintenance. 2. Code-based tools such as plantUML which was mature and solid, but required Java :|

automatic6131 4y ago

This looks really interesting. I hope a Windows installer is out soon

jmartrican 4y ago
+1 for Windows installer. In case the authors are reading this.
- alixanderwang 4y ago
  we'll get this up next week. https://github.com/terrastruct/d2/issues/96 https://github.com/terrastruct/d2/issues/96

WalterBright 4y ago

There was a popular program in the 1970s that turned Fortran into flowcharts. The flowcharts were useless, but the program was created due to some government requirement that Fortran code be accompanied by flowchats.

j_m_b 4y ago

I use Graphviz to create Entity Relationship (ER) diagrams for my database schemas. One pain point with graphviz is that once the database table schema becomes large (> 10-15 tables), the layout of the tables becomes awkward. There are times when I would like to move tables to have less overlap of relationship arrows, but this is difficult. Does D2 allow for better control of object placement in the output graph?

alixanderwang 4y ago
Not in the core language currently. You can do it on the Terrastruct web app (dragging things around after render). We're thinking about ways to better specify exact positioning in D2 CLI, perhaps something like a flag to lock in x,y coordinates that can be changed post-render.

pedrovhb 4y ago

This looks pretty great, though I'm surprised at the filesize for a simple diagram - 333kb from a simple test I made. A cat of the SVG prints out some base64 which I didn't try decoding, but I'd assume it's the bundled font that takes up most of the space? It'd be nice if it contained only the characters necessary for the diagram itself.

alixanderwang 4y ago
yeah there's overhead with the fonts bundled in. we might change this, https://github.com/terrastruct/d2/discussions/132 https://github.com/terrastruct/d2/discussions/132 i wasn't aware you could selectively choose characters for fonts, but that'd be ideal
- andix 4y ago
  Maybe don’t bundle the font by default? Can‘t you just use the standard system fonts like tailwind does, and gives quite good results? font-family: ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, "Noto Sans", sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji";

undershirt 4y ago

Thanks for the excellent example diagram in the readme. It actually seems like the best way to understand the cheating scandal.

sgt 4y ago

Getting this on macOS after installing dyld: cannot load 'd2' (load command 0x80000033 is unknown) Abort trap: 6

nhooyr 4y ago
What version of macOS are you using? We built on macOS 13.0 with go1.19.3. If you're subsantially older, you'll probably have to install from source due to the c dependencies. See https://github.com/terrastruct/d2/blob/master/docs/INSTALL.md https://github.com/terrastruct/d2/blob/master/docs/INSTALL.m...
- sgt 4y ago
  Using 10.14.6 (Mojave). I was running go 1.17 so the build didn't work at first. With go1.19 it worked and I am now running the d2 software.

pyrolistical 4y ago

Love the layout this generates, but a killer feature of mermaidjs/plantuml is it works in the browser with the document embedded in the url: https://mermaid.live/edit#pako:eNpVkEFrwzAMhf-K0GmD5A_kMFiTrpeODdbTkhxErNams2Uch1GS_Pc5yQqbTkLvew_xRuxEMRZ4CeQ1nKrGQZrnutTB9NFS30KeP00HjmDF8W2C3cNBoNfivXGXx43fLRCU43HBGKI27jpvUrn63xxPUNVH8lF8-1c5fcsE-9q86xT_X9GBk-ulPlNxpryjACWFFjO0HCwZld4eF0ODUbPlBou0KgrXBhs3J27wiiLvlYkSMGV89ZwhDVE-bq7DIoaB71BlKFVg70dePa9bN2tFGXpynyL2N2j-AZw1ZnM https://mermaid.live/edit#pako:eNpVkEFrwzAMhf-K0GmD5A_kMFiTr... https://www.planttext.com/?text=SoWkIImgAStDuU9ooazIqBLJSCp9J4wrKl18pSd9L-JYSaZDIm5A0m00 https://www.planttext.com/?text=SoWkIImgAStDuU9ooazIqBLJSCp9...

alixanderwang 4y ago
love this idea. https://github.com/terrastruct/d2/issues/153 https://github.com/terrastruct/d2/issues/153

hammeiam 4y ago

Is it possible to integrate this with a library like networkx? D2 has great layouts and seems very simple to create ad-hoc graphs, but it would also be nice to support graph data structures that you can slice up how you want, like this https://github.com/hammeiam/saddle-data-graph/blob/master/Saddle%20Data%20Graph.ipynb https://github.com/hammeiam/saddle-data-graph/blob/master/Sa...

alixanderwang 4y ago
D2 has an AST API, so you should be able to transpile from other graph libraries easily. see the second half of https://github.com/terrastruct/d2#d2-as-a-library https://github.com/terrastruct/d2#d2-as-a-library

dang 4y ago

D2: A new declarative language to turn text into diagrams - https://news.ycombinator.com/item?id=32652291 https://news.ycombinator.com/item?id=32652291 - Aug 2022 (126 comments)

alixanderwang 4y ago
Hi dang, that post wasn't posted by me and it was a premature release, where the top comments questioned why it's not open source. the original title for this was that it's now open source. hopefully it's not counted as a repost, perhaps the title could be reverted to its original to avoid any potential penalty of dupe? related: https://news.ycombinator.com/item?id=32656873 https://news.ycombinator.com/item?id=32656873
- dang 4y ago
  Ok, I've put open source back in the title.
  - alixanderwang 4y ago
    thanks

xbar 4y ago

Charming example.

darkteflon 4y ago

Just looking at the documentation on themes (https://d2lang.com/tour/themes https://d2lang.com/tour/themes) - the themes themselves are great but I can't see any way to set a dark (or alternate color) background?

alixanderwang 4y ago
ty for the suggestion, our designer will come up with some! https://github.com/terrastruct/d2/issues/158 https://github.com/terrastruct/d2/issues/158
- darkteflon 4y ago
  Wonderful - thank you!

kowlo 4y ago

I use Blockdiag - how come I never see it mentioned?

spacey 4y ago

This looks like a nice and modern improvement to PlantUML. Are there any plans for an IntelliJ plugin?

alixanderwang 4y ago
thank you! not currently

dave333 4y ago

Would love to try this out but I am having various problems with curl mostly certificates that is stopping the install. Install.sh is a bit complex for tweaking. Is there a zip or .msi or .exe I can grab to install this on Windows 10?

nhooyr 4y ago
For windows you'll have to build from source for now as we don't have prebuilt releases. install.sh cannot run on windows anyway afaik unless windows now has a POSIX shell interpreter? We're likely going to add a chocolatey package too. See https://github.com/terrastruct/d2/issues/96 https://github.com/terrastruct/d2/issues/96 See https://github.com/terrastruct/d2/blob/master/docs/INSTALL.md#from-source https://github.com/terrastruct/d2/blob/master/docs/INSTALL.m...
- dave333 4y ago
  I was hoping it would work under git bash.
  - nhooyr 4y ago
    Oh, I'll note that we should test this once we have windows releases.

euroderf 4y ago

Looks great! Since it's programmable in Go, why not go whole hog ? 1) Accept an SQL schema and automatically diagram all tables that interconnect via PK/FK references (including many-to-many). 2) Starting from main(), reflect a compiled code base (or use source files' parse results from https://pkg.go.dev/go/parser https://pkg.go.dev/go/parser) and diagram it down to some level.

alixanderwang 4y ago
(1) is on our roadmap! transpile from postgres-exported schema CSVs

tarasglek 4y ago

This is awesome as it resolves a lot of my graphviz complaints. However it seems to be missing graphviz concept of ports. I found ports to be very useful as an alternative to labelling edges for SQL foreign key relationships. Ports make graphs more compact and easier to read esp for tables with large numbers of foreign keys

willtemperley 4y ago

Having evaluated all the options in text-to-diagram.com, considered licenses, languages, openness, and how I might roll-my-own, I picked up a pencil and paper and drew the diagram I needed in five minutes. Progress made.

HeavyStorm 4y ago

This kind of library/program must be written in javascript. To be able to do this in the browser is very, very useful.

McUsr 4y ago

Thank you, thank you, thank you. I live well with your install.sh not beeing able to reckognize that I'm on Debian and have a slightly different layout than generic Linux. On the other hand, getting installations from outside repos into /usr/local/bin, isn't a bad choice over all. Me not beeing used to using curl, I didn't realize that the dry run parameter to go at the end of install command. I guess most people who downloads from github gets that. A line or two on how you do a dry run, with the command line fully spelled out wouldn't hurt though. Now that all the sour critique is out of the way, I want to repeat my thank you's, the comparative site was great, and so were the examples, and it came just in time! I'm going to use this for small simple diagrams, and some views of ER models, I'm not into the call graph, or drawing 1000's of nodes thing at the moment, it will probably work well for that too. My point is, that your graphs are actually simpler to define than using groff's pic macro package, or the stand-alone pic2graph utility. So. Thank you!!

alixanderwang 4y ago
oh hm, do you think the issue was that you're on Debian or something else (different layout that you refer to)? We'll be sure to test on a Debian machine in the future. Thank you for the feedback and kind words!

mannykoum 4y ago

Any potential integration with Latex ? not sure exactly how that would work; it would be nice to either embed d2 code in a block and make the rendering part of the latex compilation. Similar to tikz. I guess for now I can use d2 and then insert the generated svg but I would like sth closer to that holy grail of version-controlled documentation where you type and everything is magically done in one step and you store no data in the repo.

alixanderwang 4y ago
yes, we support markdown, so latex would just be another language tag. you can follow here and be notified when it's ready: https://github.com/terrastruct/d2/issues/135 https://github.com/terrastruct/d2/issues/135

metalliqaz 4y ago

Requires a monthly subscription fee to use. HARD PASS.