![D2](https://raw.githubusercontent.com/MariusAlbrecht/d2/master/./docs/assets/banner.png)
A modern diagram scripting language that turns text to diagrams.
Docs | Cheat sheet | Comparisons | Playground
![D2 Playground button](https://raw.githubusercontent.com/MariusAlbrecht/d2/master/./docs/assets/playground_button.png)
cli.mp4
Table of Contents
- What does D2 look like?
- Quickstart
- Install
- D2 as a library
- Themes
- Fonts
- Export file types
- Language tooling
- Plugins
- Comparison
- Contributing
- License
- Related
- FAQ
- Open-source projects documenting with D2
What does D2 look like?
# Actors
hans: Hans Niemann
defendants: {
mc: Magnus Carlsen
playmagnus: Play Magnus Group
chesscom: Chess.com
naka: Hikaru Nakamura
mc -> playmagnus: Owns majority
playmagnus <-> chesscom: Merger talks
chesscom -> naka: Sponsoring
}
# Accusations
hans -> defendants: 'sueing for $100M'
# Offense
defendants.naka -> hans: Accused of cheating on his stream
defendants.mc -> hans: Lost then withdrew with accusations
defendants.chesscom -> hans: 72 page report of cheating
There is syntax highlighting with the editor plugins linked below.
Rendered with the TALA layout engine.
For more examples, see ./docs/examples.
Quickstart
The most convenient way to use D2 is to just run it as a CLI executable to
produce SVGs from .d2
files.
# First, install D2
curl -fsSL https://d2lang.com/install.sh | sh -s --
echo 'x -> y -> z' > in.d2
d2 --watch in.d2 out.svg
A browser window will open with out.svg
and live-reload on changes to in.d2
.
Install
The easiest way to install is with our install script:
curl -fsSL https://d2lang.com/install.sh | sh -s --
You can run the install script with --dry-run
to see the commands that will be used
to install without executing them.
Or if you have Go installed you can install from source though you won't get the manpage:
go install oss.terrastruct.com/d2@latest
You can also install a release from source which will include manpages. See ./docs/INSTALL.md#source-release.
To uninstall with the install script:
curl -fsSL https://d2lang.com/install.sh | sh -s -- --uninstall
For detailed installation docs, see ./docs/INSTALL.md. We demonstrate alternative methods and examples for each OS.
As well, the functioning of the install script is described in detail to alleviate any concern of its use. We recommend using your OS's package manager directly instead for improved security but the install script is by no means insecure.
D2 as a library
In addition to being a runnable CLI tool, D2 can also be used to produce diagrams from Go programs.
For examples, see ./docs/examples/lib.
Themes
D2 includes a variety of official themes to style your diagrams beautifully right out of the box. See ./d2themes to browse the available themes and make or contribute your own creation.
Fonts
D2 ships with "Source Sans Pro" as the font in renders. If you wish to use a different one, please see ./d2renderers/d2fonts.
Export file types
D2 currently supports SVG and PNG exports. More coming soon.
Language tooling
D2 is designed with language tooling in mind. D2's parser can parse multiple errors from a broken program, has an autoformatter, syntax highlighting, and we have plans for LSP's and more. Good language tooling is necessary for creating and maintaining large diagrams.
The extensions for VSCode and Vim can be found in the Related section.
Plugins
D2 is designed to be extensible and composable. The plugin system allows you to change out layout engines and customize the rendering pipeline. Plugins can either be bundled with the build or separately installed as a standalone binary.
Layout engines:
- dagre (default, bundled): A fast, directed graph layout engine that produces layered/hierarchical layouts. Based on Graphviz's DOT algorithm.
- ELK (bundled): A directed graph layout engine particularly suited for node-link diagrams with an inherent direction and ports.
- TALA (binary): Novel layout engine designed specifically for software architecture diagrams. Requires separate install, visit the Github page for more.
D2 intends to integrate with a variety of layout engines, e.g. dot
, as well as
single-purpose layout types like sequence diagrams. You can choose whichever layout engine
you like and works best for the diagram you're making.
Comparison
For a comparison against other popular text-to-diagram tools, see https://text-to-diagram.com.
Contributing
Contributions are welcome! See ./docs/CONTRIBUTING.md.
License
Open sourced under the Mozilla Public License 2.0. See ./LICENSE.txt.
Related
We are constantly working on new plugins, integrations, extensions. Contributions are welcome in any official or community plugins. If you have somewhere in your workflow that you want to use D2, feel free to open a discussion. We have limited bandwidth and usually choose the most high-demand ones to work on. If you make something cool with D2 yourself, let us know and we'll be happy to include it here!
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/pleshevskiy/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
- MdBook preprocessor: https://github.com/danieleades/mdbook-d2
- ROS2 D2 Exporter: https://github.com/Greenroom-Robotics/ros-d2
- D2 org-mode support: https://github.com/xcapaldi/ob-d2
- Python D2 diagram builder: https://github.com/MrBlenny/py-d2
- Clojure D2 transpiler: https://github.com/judepayne/dictim
- JavaScript D2 diagram builder: https://github.com/Kreshnik/d2lang-js
Misc
- Comparison site: https://github.com/terrastruct/text-to-diagram-site
- Playground: https://github.com/terrastruct/d2-playground
- Language docs: https://github.com/terrastruct/d2-docs
FAQ
- 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.
- What's coming in the next release?
- I have a question or need help.
- The best way to get help is to ask on D2 Discord
- I have a feature request, proposal, or bug report.
- Please open up a Github Issue.
- I have a private inquiry.
- Please reach out at hi@d2lang.com.
Open-source projects documenting with D2
Do you have or see an open-source project with .d2
files? Please submit a PR adding to
this list (ordered by star count, desc).
- Block Protocol - The Block Protocol is an open standard for building and using data-driven blocks.
- Ivy Wallet - Ivy Wallet is an open-source money manager app for Android.
- Learn EVM Attacks - Learn & Contribute on previously exploited vulnerabilities across several EVM projects.
- BYCEPS - BYCEPS is a self-hosted web platform to run LAN parties.
- Re:Earth - A free, open and highly extensible WebGIS platform.
- Terraform OCI VSCode Server - Terraform project that deploys VSCode Server on Oracle Cloud Infrastructure.