Any output file with extension txt will use the ASCII renderer to write to it.

Here is an example of their rendering from the D2 Vim extension. The user opens a .d2 file and opens a preview window, which updates upon every save.

Code documentation​

Perhaps the most useful place for ASCII diagrams is in the source code comments. Small simple diagrams next to functions or classes can serve to be much clearer than describing a flow.

Here again the Vim extension demonstrates a functionality to write some d2 code and replace the selection with the ASCII render.

Unicode and standard ASCII​

The default character set of ASCII renders is unicode, which has nicer box-drawing characters. If you'd like true ASCII for maximum portability, you can specify this with the flag --ascii-mode=standard.

Limitations​

The ASCII renderer is a downscale of the layout determined by the ELK layout engine with some post-processing to further compact it.

• No styles are supported
  • Some will never be, e.g. animated and font don't make sense in ASCII.
  • Some may in the future with limited scope, e.g. colors when rendered to terminal.
    • By extension, themes are moot
  • Some should be considered TODOs, e.g. double-border and multiple
• Uneven spacing
  • Sometimes the downscaling results in a box with uneven spacing, e.g. a rectangle with width 5 and the label is 2 chars. Due to discrete coordinate space in ASCII renders, some outputs may look less even than their SVG counterparts.
• Certain things just can't render
  • Special text, e.g. Markdown, Latex, Code
  • Images and icons
  • UML classes and SQL tables
  • Right now these aren't special-handled -- whether removing them from the diagram or using some placeholder is the right choice is tbd.
• Not all shapes are supported
  • Here's what all the shapes render as in ASCII. Some of these, like cloud and circle, have curves that don't translate well to ASCII. We render these as a rectangle and add a little icon for what it's supposed to represent in the top-left. These are subject to change. For now we recommend rendering without custom shapes.

Try it yourself​

This is live now in the D2 Playground. Try opening the below code block (click top right of it).

The C4 Model is a loose framework. Unlike UML, which says these symbols always and must mean certain things, the C4 model is a set of diagramming concepts. It's language and tool agnostic, and these powerful concepts have proven to provide software projects with clean, mature architecture diagrams.

With the latest 0.7 release of D2, we filled the gaps in the language to have first-class support of these concepts:

1. A new suspend keyword which, along with existing D2 features, lets you define one model and reuse them across different views.
2. Markdown labels on shapes allow you to give richer textual descriptions with font hierarchy.
3. A new c4-person shape that is more conducive to holding longform labels.
4. A C4 theme for diagrams to be conveniently on-brand recognizable.
5. A new d2-legend variable to easily make beautiful legends.

Whether you choose to use these new features specifically for C4 model diagrams is up to you. Much of this feature set was requested for other purposes. What's important are the good practices it enables, which can be applied broadly across all sorts of diagrams.

In this article, I'll demonstrate how you can make C4 diagrams in D2. If you'd like more detail on using a specific feature, you'll find dedicated sections in the docs.

One model, multiple views​

Let's take a look at how the new suspend keyword can be used to slice and dice a model into a variety of views.

First we define a medium-sized diagram using the new C4 theme, c4-person shape, and markdown labels.

Show only relationships to API Application​

Let's say we want to create a view for the API team that only includes what's relevant for them. We'll use the same code as the above, but add 2 sections:

1. "Suspend" all models​

Use globs to target everything declared so far and suspend them. These will be removed unless "unsuspended" later on. Suspended objects and connections are effectively the models.

2. Unsuspend models we use for our view​

Now we use globs to declare which models we want to show up. We do this by "unsuspending" them.

Result​

Runnable code:

Show high-level overview​

Let's make a high level overview with the same concepts. The only change here is how we unsuspend things.

And since there are connections between inner shapes of Internet Banking System to other components, we'll make some connections that capture the general dependency.

Runnable code:

Tags and filters​

Let's say your repository of models is large; maybe everyone in your cross-functional team is pushing their own models to this file.

To give an example of a small repository:

To reuse these models for a specific domain, we can filter by their classes (tag in C4 vernacular). Assuming the models are in their own file, we can create something like a CustomerInterface.d2 file, which imports these models, suspends all, and unsuspends the ones that have the customer-facing class.

Now we can add some connections to create a diagram out of these pre-existing models.

Legend​

To create a legend for this diagram, we declare it as a variable under d2-legend.

Think of d2-legend as a mini diagram of its own, but with a special layout where every shape and connection is deconstructed into a table. If something has opacity 0, it is excluded in the table (this way we can have legends that only show connections, for example).

Notice the legend in the bottom right corner.

Google Maps zooming​

Lastly, a core concept of C4 diagrams is this notion of zooming in and out of different levels of abstraction. The 4 in C4 stands for the 4 levels of abstractions that it recommends. Let's take a look at how that can be achieved. For this example, we'll define two diagrams of code that represent a zoomed in view of the components.

Example code diagram for ATM Banking System

Example code diagram for Notification System

Linking together​

Now let's link these up using the layers feature.

All that's needed is to declare the 2 code diagrams as layers and add the link property to whichever shape we want to be able to zoom into them.

We can export this to a PDF format. If you download it and click on notification or banking, it'll take you to those respective zoomed-in code views.

To recap, you'd split it out into those 4 files and use imports for modularity:

1. models.d2: where models are defined
2. customer-components.d2: where you import models
3. banking-code.d2: code diagram for banking system
4. notification-code.d2: code diagram for notification system

You can easily flesh this out further by having files for the styling, for higher levels of abstraction (e.g. for context diagrams).

It's not D2's primary function, but rather a natural byproduct of a powerful language. D2 built features for grid diagrams and animations, and users built pixel art. And now, with Markdown and Powerpoint, D2 is the easiest way to programmatically create PowerPoint presentations.

Let's look at a simple example first, and then a complex one at the end.

Simple example​

• Download: cult.pptx
• Google Slides: https://docs.google.com/presentation/d/1CnAPcvsh1B4J3nVppNDInm2oTquhCV58/view

To produce this:

• install D2
• make a .d2 file named input.d2
• copy the below
• run d2 input.d2 cult.pptx.

Complex example​

The above is pure text. Let's look at an example with diagrams and images.

Be sure to go into Present mode to click on objects and navigate around.

• Download: wcc.pptx
• Google Slides: https://docs.google.com/presentation/d/18rRh4izu3k_43On8PXtVYdqRxmoQJd4y/view

The source code for this is a bit longer, and can be found here.

Limitations​

Note that the boxes aren't native PowerPoint boxes that you can resize, and the text isn't text you can edit. It's very much a "view-only" output. This is a v1 that's just been released. Perhaps this will change in the future and we can map things to its PowerPoint equivalent, especially if there's enough demand and usage.

D2 source to reproduce this is here: here, rendered with these parameters.

Brief factsheet:

• Single file, weights 88kb, the vast majority is the embedded fonts so that it looks the same everywhere.
• Well-formatted, readable D2 text (i.e. has newlines) is 85 lines.
• Configurable. This animation has 1400ms intervals, but if you want the animation to linger for longer and shorter, simply change the flags.
• Easily split into 2 separate SVGs (the default behavior of CLI when a flag is not passed in to animate).

Use cases​

Show change​

Typically, when you're making a diagram primarily to show change in a single image, you put them side by side. And the user scans. Their eyes are darting back and forth, piecing together the deltas.

Instead, you can overlay and switch back and forth in place, making that process much easier and clarifying the differences.

Showing versions is a form of showing change. An example of this is conveyed in the first example above.

Show steps​

Take the viewer through a sequence of steps

Or a journey to build up to something.

Ergonomics will be better soon​

D2 is not yet 1.0. Of the many things planned in the near term, better ergonomics for creating these are a priority. The source code for all of these diagrams can be found here. Some of these are currently verbose and repetitive. We've released early to get feedback from the community, but in-progress things like globs (being able to target objects with *) and classes will make creating these animations much easier than they currently are.

--animate-interval is available to use in D2 0.3.0 (install here), hope you can check it out and let us know what you think!

When you pass the sketch flag like so, you'll get a diagram that kind of looks hand-drawn.

Playground link to modify diagram

Most of the credit here goes to RoughJS for providing such an excellent library for converting normal SVG paths into imperfect ones, making the slight inaccuracies that our hand might when whiteboarding these types of diagrams in real life. Preet is an example of just a solo developer responsible for maintaining a small project that's behind-the-scenes for what is now a good chunk of a lot of diagrams you see on the web today! Please consider sponsoring him if you like this aesthetic.

For the most part, the implementation was as simple as using this library to convert paths, tune the parameters (e.g. we don't want paths to look as roughly drawn as shapes), and pick an appropriate font to match the aesthetic. Since D2 runs on Go and RoughJS is obviously a Javascript library, we embed a pure Go Javascript-runner as the bridge.

However, we did make one significant modification to this method: background fills.

RoughJS comes with many default fill patterns, but we thought they were all too jarring for diagramming. For example, this is a render on Excalidraw, another diagramming tool that leverages RoughJS.

While this does emulate a color-pencil type of fill, true to a hand-drawn aesthetic, it also makes the contents hard to read. We looked into options like putting a mask on the text so it dodges those lines, but even if it solves that problem, it brings a sharpness to the diagram that looks a bit intense, like we're aggressively coloring in something.

The solution that our designer came up with is to overlay a subtle texture of streaks that blends into the background. And to make it visible on all colors, the method of blending changes depending on how bright the background color is.

If you inspect the main diagram of this post, you can see it in effect with the various brightness of fills.

It even works with animated connections!

How does this work? How can a diagram have two themes?

Try opening up your system preferences and toggling between light and dark mode.

Playground link to modify diagram

Note: playground does not have support to set a dark theme yet

What you should have seen is the above diagram adapting to your preference. If you didn't want to follow along, here's two PNGs of what it would've transitioned between:

This means that if your website already supports a responsive experience for visitors that prefer light mode and dark mode, it takes zero extra work to include a D2 diagram that'll adapt to light preferences. The alternative method used across the web currently is to include two diagrams -- and toggle which one gets shown with media queries.

This is currently a new feature, and we are working on adding more themes and considering including it by default.

How does this work? The diagram actually is a high level overview of it. All the shapes and connections are color coded, which takes into account their depth, shape type, and a few other factors. The themes then provide a color for that color code in CSS. Since classes are secondary to attributes and styles, any explicitly set styles are not overwritten. The dark mode theme simply applies a different set of colors to the color codes with a media query.

Shoutout to first-time contributor https://github.com/vfosnar, who came up with the idea and juggled commits in between high school exams to implement this <3.