Add diagrams to your Astro site with D2

In a previous post I compared Mermaid.js and D2, reaching the conclusion that D2 is an all-around better diagramming tool, especially if you’re building diagrams for a static website like a blog or documentation site. This post will show you how to add D2 diagrams to your Astro blog. We’ll configure a docker-based build process that generates diagrams from D2 code blocks in your MDX articles at build time.

This post builds on HiDeoo’s excellent astro-d2 integration, which he walks through in his blog post on adding diagrams to a Starlight site. We’ll extend his work to show how to use Docker to generate diagrams at build time, and configure astro-d2 to place diagrams into a directory that we exclude from git and docker to keep our git repository clutter-free.

step 1: install D2 for local development

First, install the D2 CLI tool on your local machine so you can preview the diagrams you’re building. As per D2’s official installation guide, the easiest way to do this is by running the shell script they provide, which detects your platform and chooses the most suitable installation method:

# With --dry-run the install script will print the commands it will use
# to install without actually installing so you know what it's going to do.
curl -fsSL https://d2lang.com/install.sh | sh -s -- --dry-run
# If things look good, install for real.
curl -fsSL https://d2lang.com/install.sh | sh -s --

I’ve used this script on both Linux and MacOS without issue. If you’re on MacOS and have Homebrew installed, you can also install D2 using brew install d2. I haven’t tried installation on Windows; TerraStruct provides prebuilt .msi installers for Windows, which should make the process simple if they work as advertised.

step 2: install astro-d2

astro-d2 installs like any other Astro integration:

npx astro add astro-d2

step 3: ignore generated diagrams

Excluding the diagrams that astro-d2 generates from source control removes noise from your git repository. Diagrams are large files that are generated with filenames containing the source MDX filename and diagram order in the MDX document.

• If you change the order of the diagrams in an MDX file or add a new diagram, you’ll end up with a lot of file changes that don’t reflect changes to your actual source code.
• Same goes if you change the name of the MDX file; diagrams with the old filename will hang around until you manually clean them up.
• Locally built diagrams will be overwritten by the ones generated at build time anyway, so there’s no reason to commit them to your git repository. For the same reason, locally built diagrams should be added to your .dockerignore file.

Assuming you kept the default output directory of d2, as configured above, add the following lines to the .gitignore file in the root of your Astro project:

# generated d2 diagrams
public/d2/

You should also add the same lines to the .dockerignore file in the root of your Astro project.

step 4: add D2 to your Docker build

This step installs the D2 CLI tool into the image that will be used to build your Astro static site. If you’re comfortable with the security implications of running D2’s official installation script in your Docker container¹, it’s easy to add D2 to a node-based builder image:

# Base stage for building the static files
FROM node:lts AS base
WORKDIR /app
COPY package*.json ./
RUN npm install
# run d2 install script
RUN curl -fsSL https://d2lang.com/install.sh | sh -s --
COPY . .
RUN npm run build

# NOTE: nginx for serving static files goes here!

step 5: add diagrams to your Astro blog posts

Adding a D2 diagram in an MDX file is now as simple as adding a code block with the d2 language:

```d2 sketch
# A simple flowchart
direction: right
D2 Blocks {shape: document}
D2 Blocks -> Astro D2: processes {style.animated: true}
Astro D2 -> SVGs: generates {style.animated: true}
```

The block above generates this diagram:

See the Astro-D2 docs for more information on the configuration options available, which can be set globally in astro.config.ts or overridden on a per-code block basis using attributes, like sketch in the example above.

And of course be sure to check out the D2 docs for more information on how to use D2 to create all sorts of diagrams.

conclusion

For such a young framework, Astro has a surprisingly robust ecosystem of integrations, many of which have yet to receive the love they deserve. Astro-D2 is a well-documented, actively maintained integration that allows you to include professional-looking diagrams in your static site without slowing down your build times or adding client-side dependencies to your project.

D2 is a powerful tool that’s uniquely well suited to generating diagrams for static sites at build time. The DSL (domain-specific language) is concise and expressive, and the text-based approach makes it easy to manage the content of your diagrams. D2 still has a long way to go to catch up wtih Mermaid in terms of popularity, but as the tool matures I expect that to change.