D2: A Modern Diagram Scripting Language

D2: A Modern Diagram Scripting Language That Turns Text into Diagrams

D2 is designed for people who want to express diagrams as plain text, yet demand the power and flexibility of a programming approach. It blends human-readable syntax with a pluggable rendering pipeline, making it possible to define, render, and customize diagrams in a repeatable, programmatic way. Whether you’re documenting software architecture, system designs, or data flows, D2 aims to be expressive, approachable, and highly adaptable to your workflow.

What does D2 look like?

At its core, D2 presents a succinct, code-first way to describe graphs, networks, and architectures. The language emphasizes readability and structure, enabling you to model entities, relationships, and visual styling without switching to a separate diagram editor. A compact sample illustrates the feel of D2:

• Entities such as: cells, towers, transmitters, portals, data processors, and users.
• Connections that represent flows and actions: sending, making calls, accessing UI, persisting logs.
• Visual hints like shapes, styling, and directional arrows to convey layout and emphasis.

Here is a representative snippet to give you a sense of the syntax (abridged for readability):

d2 vars: { d2-config: { layout-engine: elk, code theme-id: 300 } } network: { cell tower: { satellites: { shape: stored_data style.multiple: true } } transmitter satellites -> transmitter: send online portal: { ui: {shape: hexagon} } data processor: { storage: { shape: cylinder style.multiple: true } } cell tower.transmitter -> data processor.storage: phone logs } user: { shape: person width: 130 } user -> network.cell tower: make call user -> network.online portal.ui: access { style.stroke-dash: 3 } api server -> network.online portal.ui: display api server -> logs: persist logs: {shape: page; style.multiple: true} network.data processor -> api server

This kind of text-driven description is then turned into vivid diagrams by D2’s rendering engines, which you can tailor to your preferences and project requirements. To see a concrete rendering of a D2 script, you can view an example diagram rendered from the sample above. The image below showcases how D2 translates textual definitions into a visual diagram:

If you want to experiment visually, you can open the playground to rend­er D2 code in your browser and interact with live diagrams as you type. The playground provides an immediate, side-by-side coding and rendering experience, helping you iterate quickly on layouts and styles. For quick exploration, you can click the Playground button in the documentation to launch the interactive environment.

Quickstart: a fast path to SVGs

The easiest entry point for trying D2 is to use it as a command-line tool that converts .d2 files into SVGs (and other formats). Here’s a concise path to get you up and running:

• Create a tiny D2 script and render it:
• Create a file in.d2 containing a simple pipeline like x -> y -> z
• Run D2 in watch mode to produce an output SVG that updates as you edit:
  • d2 --watch in.d2 out.svg

As you save in.d2, your browser window will refresh to show the latest diagram. This live feedback makes it a joy to prototype diagrams quickly and keep your diagrams in sync with your source.

Install: getting D2 onto your machine

D2 provides a straightforward install experience, plus options to install from source if you prefer. The recommended path is to use the install script:

• Install:
• curl -fsSL https://d2lang.com/install.sh | sh -s --
• Optional: perform a dry-run to see exactly what commands would be executed
• If you have Go installed, you can also install directly from source:
• go install oss.terrastruct.com/d2@latest
• Note: building from source may not include the manpage
• Uninstall:
• curl -fsSL https://d2lang.com/install.sh | sh -s -- --uninstall

For deeper, platform-specific guidance, consult the official installation documentation. The installation script is designed to be secure and transparent, with an emphasis on letting users prefer their OS package managers when possible for security and maintenance benefits.

D2 as a library: diagrams from code

D2 isn’t limited to a standalone CLI. It can be used as a library within Go programs, enabling you to generate diagrams directly from code. This opens up a world of automation: you can generate diagrams as part of build scripts, documentation pipelines, or tooling that reflects your software’s current state. If you want to see a complete, runnable example of using D2 as a library in a real-world workflow, there is a dedicated blog post that walks through the process step by step. Additionally, you can explore the examples provided in the repository under docs/examples/lib to see how this approach can fit into your project.

Themes: styling that ships with D2

D2 ships with official themes that style diagrams “out of the box,” letting you achieve a polished, consistent look without manual tuning of every element. Themes enable you to express different visual languages—describing how colors, fonts, node shapes, and edge styles should behave across many diagrams. You can browse available themes and contribute your own through the theme directory (d2themes). The ability to switch themes helps teams align diagrams with brand guidelines or documentation standards without rewriting layout rules.

Fonts: typefaces that render well

By default, D2 renders text with a clean, readable font—Source Sans Pro. If your project requires a different typographic voice, D2 provides access to alternative fonts via the rendering subsystem (d2renderers/d2fonts). This makes it straightforward to tailor the typography to match your document style, product branding, or accessibility needs, all while keeping the diagrams legible and aesthetically pleasing at various sizes.

Export file types: SVG, PNG, PDF

D2 supports multiple export formats to fit different use cases:

• SVG: ideal for scalable, browser-friendly diagrams embedded in web pages or documentation.
• PNG: a raster option suitable for static images in slides or offline materials.
• PDF: perfect for printable, portable diagrams that maintain fidelity in documents.

More formats are on the roadmap, with ongoing work to broaden the export capabilities and improve fidelity across targets.

Language tooling: making diagrams maintainable

D2 is designed with tooling in mind. The parser is capable of reporting multiple errors in a broken program, which is essential for large diagrams or when diagrams are generated programmatically. In addition, D2 includes:

• Autoformatter: keeps your D2 sources consistently styled and readable.
• Syntax highlighting: aids in quickly understanding structure as you type.
• Plans for Language Server Protocol (LSP) support: enabling richer editor integrations for faster development and better error feedback.
• Editor extensions: available for popular environments (VSCode, Vim, etc.) to streamline editing, navigation, and validation of D2 diagrams.

The combination of robust tooling and a readable syntax makes D2 well-suited for teams building large diagram libraries or documentation systems.

Plugins: extensibility and rendering pipelines

D2 is designed to be extensible and composable through plugins. The plugin system lets you customize the rendering pipeline and swap out layout engines to suit your diagram’s needs. Plugins can be bundled with the D2 build or installed independently as standalone binaries. There are several layout engines you can choose from:

• Dagre (default, bundled): A fast, directed graph layout engine that produces layered or hierarchical layouts. It’s based on Graphviz’s DOT algorithm and performs well for general graph structures.
• ELK (bundled): The Eclipse Layout Kernel is a versatile engine well-suited for node-link diagrams with clear directions and port semantics.
• TALA (binary): A layout engine specifically designed for software architecture diagrams. It requires a separate installation.

D2’s architecture supports future integrations with other layout engines, including dot (Graphviz) and specialized sequence diagram types. This flexibility lets you pick the engine that best matches your diagram’s semantics and aesthetics, while staying within a consistent language and toolchain.

Comparison: how D2 stacks up

For a quick sense of where D2 sits in the landscape of text-to-diagram tools, you can consult the comparison site that aggregates and contrasts features across multiple projects. This resource highlights differences in syntax, capabilities, and ecosystem tooling, helping you decide whether D2 fits your needs or if another tool better suits your constraints. A direct comparison reference is available via the project’s comparison page.

Contributing: join the journey

D2 is open source and welcomes contributions from the community. If you’re interested in shaping the future of the language, the repository provides clear guidance on how to contribute. Practical starting points include:

• Reviewing the contribution guidelines to understand coding standards, testing requirements, and review processes.
• Proposing enhancements to the parser, renderers, or tooling.
• Contributing examples, themes, or plugins to showcase the versatility of D2.
• Reporting issues or proposing features through the project’s issue tracker.

License: open source under MPL 2.0

D2 is released under the Mozilla Public License 2.0. This license encourages open collaboration while allowing vendors to use and extend the software in a way that respects the code’s license terms. The license text is included in the repository for reference.

Related: plugins, integrations, and ecosystem

D2’s ecosystem includes a broad range of official and community-driven plugins, extensions, and integrations. The “Related” section lists notable projects and tooling that complement D2, including editors, plugins, and adapters that help embed D2 into broader workflows. Some prominent entries include:

• Official plugins
• VSCode extension: https://github.com/terrastruct/d2-vscode
• Vim extension: https://github.com/terrastruct/d2-vim
• Obsidian plugin: https://github.com/terrastruct/d2-obsidian
• Slack app: https://d2lang.com/tour/slack
• Discord plugin: https://d2lang.com/tour/discord
• Community plugins
• Tree-sitter grammar: https://github.com/ravsii/tree-sitter-d2
• Emacs major mode: https://github.com/andorsk/d2-mode
• Goldmark extension: https://github.com/FurqanSoftware/goldmark-d2
• Telegram bot: https://github.com/meinside/telegram-d2-bot
• Postgres importer: https://github.com/zekenie/d2-erd-from-postgres
• Structurizr to D2 exporter: https://github.com/goto1134/structurizr-d2-exporter
• And many more show up in the ecosystem, including tools for documentation pipelines, editors, and data modeling.

Community and miscellaneous resources expand the reach of D2 beyond the core language, enabling ecosystem-wide adoption, customization, and automation. If you’re building a workflow that benefits from programmatic diagram generation, there’s a good chance you’ll find a plugin or integration in this growing catalog.

Notable open-source projects documenting with D2

A number of open-source efforts have used D2 to document architectures, data flows, and software diagrams. These projects illustrate how D2 can be adopted in real-world scenarios and integrated with modern tooling. Notable examples include:

• ElasticSearch: diagrams for queue and broker flows in the beats library
• Sourcegraph: engineering managed-services telemetry gateway diagrams
• Temporal: matching-context diagrams for workflows
• Tauri: inter-process communication diagrams for the desktop environment
• Rust GUI framework projects showcasing architecture diagrams
• IntelliJ-based projects with Diagrams embedded in documentation
• Coder: templates and templates-in-code examples
• UC Berkeley Hammer: architecture diagrams for hardware and software interactions
• Coronacheck: client-side diagrams for health-check applications
• Block Protocol: open standard diagrams describing data-driven blocks
• Dagger: a programmable CI/CD engine with graph representations
• Ivy Wallet: financial app diagrams showing calculation flows
• LocalStack: cloud service emulation diagrams
• Queue Library: diagrams illustrating concurrency and worker pools

These examples demonstrate D2’s utility in communicating complex systems succinctly and reproducibly, making diagrams an integral part of documentation, onboarding, and design reviews.

FAQ: quick questions answered

• Does D2 collect telemetry?
• No. D2 does not use an internet connection after installation, except to check for version updates from GitHub periodically.
• Does D2 need a browser to run?
• No. D2 can run entirely server-side; rendering occurs within the toolchain itself.
• What’s coming in the next release?
• See the changelog for the upcoming features and fixes.
• I have a question or need help.
• The best way to get help is to ask on the D2 Discord server.
• I have a feature request, proposal, or bug report.
• Please open a Github Issue to start a discussion.
• I have a private inquiry.
• Reach out at hi@d2lang.com.

Playgrounds, demos, and live examples

The D2 ecosystem includes a playground where you can test scripts in real time, observe how changes affect layout and style, and compare different layouts or themes. This hands-on environment accelerates learning and helps teams evaluate D2 for their documentation and architecture diagrams. For quick experimentation, you can follow the inline links to the playground and start testing with minimal setup. A visual cue for the playground is included in the documentation as a button that opens the playground in a new tab.

Notable excerpts and examples you’ll encounter

• A compact, well-documented “What does D2 look like?” section that presents a complete script with nodes, edges, and styling directives.
• A “Quickstart” section that demonstrates installing D2, creating a small script, and generating an SVG.
• A “Plugins” section that lists layout engines with descriptions of their strengths and typical use cases.
• A “Themes” and “Fonts” section that explains how to tailor the look and feel of diagrams to fit your brand or project.
• A “D2 as a library” section highlighting programmatic generation of diagrams from Go code, with references to examples and a blog post for deeper learning.

Putting it all together: why choose D2

• Readable, text-first diagrams: D2 emphasizes readability and maintainability, enabling diagrams to be authored, reviewed, and version-controlled like code.
• Flexible rendering: with pluggable layout engines and a pipeline that can be extended with plugins, you can optimize layouts for specific diagram types and performance characteristics.
• Rich tooling: a focus on language tooling—parsing, autoformatting, syntax highlighting, and planned LSP support—helps teams maintain large diagram sets with confidence.
• Broad export options: SVG, PNG, and PDF exports cover both online and offline documentation needs, from web docs to printed handbooks.
• Strong ecosystem: official and community plugins, extensions, and integrations enable D2 to fit neatly into IDEs, documentation systems, and CI/doc pipelines.

Images embedded in the article

• A vivid banner at the top to set the visual tone and introduce D2’s modern diagram scripting philosophy.
• An example diagram rendered from D2 text to illustrate the translation from script to visual representation.
• A visual playground button to hint at live experimentation in the browser.

If you’re curious about diagram scripting and you love keeping diagrams as code, D2 offers a compelling blend of readability, flexibility, and extensibility. From quickstart SVGs to production-grade pipelines that generate diagrams from code, D2 is designed to integrate smoothly into modern development and documentation workflows. Whether you’re documenting a microservices architecture, mapping a data flow, or simply exploring a new way to communicate complexity, D2 provides a practical, scalable path—from text to diagrams.