Add diagrams to your Starlight documentation using D2

Multiple solutions exist to embed diagrams declaratively in your Markdown content and render them on your documentation website. They usually involve leveraging diagramming tools like Mermaid, PlantUML, or Graphviz. Most of the time, rendering such diagrams comes with various trade-offs, like embedding JavaScript on your pages to render the diagrams, using fairly slow solutions to render the diagrams at build time, e.g. Playwright, or not having proper dark mode support.

This guide will show you one possible way to add diagrams to your Starlight documentation using D2, a Declarative Diagramming tool.

Why D2?

D2 is a declarative diagramming tool that allows you to turn text into diagrams.

The default output format of D2 is an SVG file containing the diagram and its associated CSS styles. This file is meant to be used in a web context, which makes it a perfect fit for documentation websites on top of being vector-based, scalable, and can also be animated.

D2 also includes a lot of powerful features out of the box, such as themes, an adaptative dark mode, sketching, animations, and much more. The D2 command-line tool which is the most common way to use D2 is also very fast which makes it a great fit for build-time rendering.

Learn more about D2 by visiting the official website.

Prerequisites

You will need to have an existing Starlight website.

Install D2

The D2 CLI will be used to render diagrams and will need to be installed on your machine. It can be installed on many platforms, including Windows, macOS, and Linux using different methods such as various package managers, Docker, or manually.

You can learn how to install D2 by visiting the official installation guide. For example, on macOS, you can install D2 using Homebrew:

brew install d2

Install astro-d2

Start by installing the astro-d2 package which is an Astro integration and remark plugin to transform D2 Markdown code blocks into diagrams relying on the D2 CLI.

npx astro add astro-d2

pnpm astro add astro-d2

yarn astro add astro-d2

bun run --bun astro add astro-d2

nr astro add astro-d2

Add diagrams

To declare a diagram, you can use a Markdown code block which is indicated by a block with three backticks ``` at the start and end and by specifying the d2 language after the opening backticks.

---
title: My content page
---

## My heading

The content of my Starlight page.

```d2
Documentation -> Website: Starlight
```

The above example will render the following content:

My heading

The content of my Starlight page.

The Astro D2 integration can be globally configured in your astro.config.mjs file to change the behavior and appearance of all diagrams. Various attributes can also be used to customize the appearance of individual diagrams.

---
title: My content page
---

## My heading

The content of my Starlight page.

```d2 sketch pad=50
direction: right

Documentation -> Starlight -> Website: {style.animated: true}
```

The above example will render the following content:

My heading

The content of my Starlight page.

You can learn more about the various features and options of Astro D2 by visiting the official documentation.

Deployments

Under the hood, the Astro D2 integration will use the D2 CLI to render the diagrams and output the resulting SVG files in the public/d2/ ¹ directory of your Astro project.

When deploying your Starlight website, the same process will by default be used to render the diagrams which means that the D2 CLI will need to be installed on the deployment environment.

If for some reason you cannot easily install D2 on your deployment environment, you can use the skipGeneration configuration option to disable the generation of diagrams on specific platforms. This will require you to build your website and commit diagrams before deploying your site. To read more about this approach, you can check the deployment guide in the Astro D2 documentation.