🚨 Before we begin, and also because this drop talks about Visual Studio Code, please see this security bulletin about CVE-2022-41034 — which details a new remote code execution weakness in VS Code. While this issue mainly impacts GitHub Codespaces, github.dev, and the web-based VS Code for the Web, it is possible for cleverly positioned attackers to also compromise VS Code desktop installations as well.

D2

There is no shortage of text-to-diagram domain-specific languages (DSL) and tooling, but there is always room for improvement in complex problem spaces.

D2 is a new diagramming language that was recently open sourced (by Terrastruct). It's aimed at developers/engineers and has a goal of ensuring creating complex diagrams is a pleasant experience. Diagramming GUIs and even many diagramming DSLs tend to get very unwieldy as the scope of a diagram grows in complexity and size). It also favors readability over prototyping speed since humans have to read these things, too. And, let's face it, “prototyping” is really just a fancy way of saying “creating foundational technical debt.” Despite this focus on readability, D2 also comes with sensible defaults that do speed up initial diagram creation. Finally, one hidden component of internet browsers is how tolerant they are with broken HTML that they're asked to render. Lots of programs die miserably on malformed input, and leave you to figure out what broke:

Aaron Bockover @abock

@timeyoutakeit You need a YAML ruler.

1:28 PM ∙ Apr 13, 2019

---

116Likes21Retweets

This is not the case with D2, and does its best to provide sane warnings while it renders your busted D2 spec.

On macOS you can:

brew tap terrastruct/d2
brew install d2

The rest of you can:

curl -fsSL https://d2lang.com/install.sh | sh -s -- --dry-run

then READ THE OUTPUT of that command and hand-type the incantations. Do not get used to these “pipe to curl” suggestions (the above just prints vs executes the commands; it still sickens me that l33t members of the R community have somewhat normalized this behavior, there).

Intrepid readers may want to grab the Golang source and build it, especially since I'll be dropping project ideas in a teensy bit.

You can, and should, walk through the examples to get a feel for the DSL, and keep this cheat sheet handy.

This is an example D2 spec which you can also find in the first link in this section (since Substack will inevitably render this poorly):

aws: {
  db: "" {
    icon: https://icons.terrastruct.com/azure/Databases%20Service%20Color/Azure%20Database%20for%20PostgreSQL%20servers.svg
    shape: image
  }

  cache: "" {
    icon: https://icons.terrastruct.com/azure/_Companies/Azure%20Cache%20Redis%20Product%20icon.svg
    shape: image
  }

  ec2: "" {
    icon: https://icons.terrastruct.com/aws/_Group%20Icons/EC2-instance-container_light-bg.svg
    shape: image
  }

  ec2 <-> db: get persisted data
  ec2 <-> cache: get temporal data
}

gcloud: {
  db: "" {
    icon: https://icons.terrastruct.com/azure/Databases%20Service%20Color/Azure%20Database%20for%20PostgreSQL%20servers.svg
    shape: image
  }
}

aws.db -> gcloud.db: backup

dev: "" {
  icon: https://icons.terrastruct.com/essentials/005-programmer.svg
  shape: image
}

github: "" {
  icon: https://icons.terrastruct.com/dev/github.svg
  shape: image
}

dev -> aws.ec2: ssh
dev -> github: version control

And, this is the rendered version using one of the alternate layout options:

I think D2 has a solid, focused use, hence me including it here, and suggesting folks learn and possibly extend it.

Your Mission(s)!

Some D2 plugins/extensions already exist:

• Obsidian plugin (w/rendering)

• vim plugin (syntax highlighting)

• VS Code plugin (syntax highlighting)

Some project ideas:

• generate some practical, “real world” example (complex) D2 specs so others can learn more about D2

• integrate a new layout engine into D2. The dagre one shows how you can use the output of JavaScript-based layout engines right in Go/D2. igraph has tons of options.

• extend the VS Code plugin to support active rendering (i.e. live review). D2 already has support for “server mode”, which means it might not be too much work to add live preview functionality for it in VS Code

• write a Sublime Text syntax highlighter extension for the D2 DSL

• build a Quarto extension so folks can include D2 specs in markdown and have it weaved into the output documents (this may require some Pandoc/Lua hacking as well).

• create an R/PyPI package that integrates & wraps the library version of D2

• design a new theme

• write a blog post about D2

• make a Twitch/YouTube (or whatev you cool kids use these days) introductory video/tutorial

  Share

FIN

If you need further pointers for any of the project ideas, hit me up wherever you're most comfortable! ☮

#D2 #Diagram #WPE