1<div align="center">
2 <img src="./docs/assets/banner.png" alt="D2" />
3 <h2>
4 A modern diagram scripting language that turns text to diagrams.
5 </h2>
6
7[Docs](https://d2lang.com) | [Cheat sheet](./docs/assets/cheat_sheet.pdf) | [Comparisons](https://text-to-diagram.com) | [Playground](https://play.d2lang.com)
8
9[](https://github.com/terrastruct/d2/actions/workflows/ci.yml)
10[](https://github.com/terrastruct/d2/actions/workflows/daily.yml)
11[](https://github.com/terrastruct/d2/releases)
12[](https://discord.gg/NF6X8K4eDq)
13[](https://twitter.com/terrastruct)
14[](./LICENSE.txt)
15
16<a href="https://play.d2lang.com">
17<img src="./docs/assets/playground_button.png" alt="D2 Playground button" width="200" />
18</a>
19
20https://user-images.githubusercontent.com/3120367/206125010-bd1fea8e-248a-43e7-8f85-0bbfca0c6e2a.mp4
21
22</div>
23
24# Table of Contents
25
26<!-- toc -->
27- [What does D2 look like?](#what-does-d2-look-like)
28- [Quickstart](#quickstart)
29- [Install](#install)
30- [D2 as a library](#d2-as-a-library)
31- [Themes](#themes)
32- [Fonts](#fonts)
33- [Export file types](#export-file-types)
34- [Language tooling](#language-tooling)
35- [Plugins](#plugins)
36- [Comparison](#comparison)
37- [Contributing](#contributing)
38- [License](#license)
39- [Related](#related)
40 - [Official plugins](#official-plugins)
41 - [Community plugins](#community-plugins)
42 - [Misc](#misc)
43- [FAQ](#faq)
44- [Notable open-source projects documenting with D2](#notable-open-source-projects-documenting-with-d2)
45
46## What does D2 look like?
47
48```d2
49# Actors
50hans: Hans Niemann
51
52defendants: {
53 mc: Magnus Carlsen
54 playmagnus: Play Magnus Group
55 chesscom: Chess.com
56 naka: Hikaru Nakamura
57
58 mc -> playmagnus: Owns majority
59 playmagnus <-> chesscom: Merger talks
60 chesscom -> naka: Sponsoring
61}
62
63# Accusations
64hans -> defendants: 'sueing for $100M'
65
66# Claim
67defendants.naka -> hans: Accused of cheating on his stream
68defendants.mc -> hans: Lost then withdrew with accusations
69defendants.chesscom -> hans: 72 page report of cheating
70```
71
72> There is syntax highlighting with the editor plugins linked below.
73
74<img src="./docs/assets/syntax.png" alt="D2 render example" />
75
76> Rendered with the TALA layout engine.
77
78> For more examples, see [./docs/examples](./docs/examples).
79
80## Quickstart
81
82The most convenient way to use D2 is to just run it as a CLI executable to
83produce SVGs from `.d2` files.
84
85```sh
86# First, install D2
87curl -fsSL https://d2lang.com/install.sh | sh -s --
88
89echo 'x -> y -> z' > in.d2
90d2 --watch in.d2 out.svg
91```
92
93A browser window will open with `out.svg` and live-reload on changes to `in.d2`.
94
95## Install
96
97The easiest way to install is with our install script:
98
99```sh
100curl -fsSL https://d2lang.com/install.sh | sh -s --
101```
102
103You can run the install script with `--dry-run` to see the commands that will be used
104to install without executing them.
105
106Or if you have Go installed you can install from source though you won't get the manpage:
107
108```sh
109go install oss.terrastruct.com/d2@latest
110```
111
112You can also install a release from source which will include manpages.
113See [./docs/INSTALL.md#source-release](./docs/INSTALL.md#source-release).
114
115To uninstall with the install script:
116
117```sh
118curl -fsSL https://d2lang.com/install.sh | sh -s -- --uninstall
119```
120
121For detailed installation docs, see [./docs/INSTALL.md](./docs/INSTALL.md).
122We demonstrate alternative methods and examples for each OS.
123
124As well, the functioning of the install script is described in detail to alleviate any
125concern of its use. We recommend using your OS's package manager directly instead for
126improved security but the install script is by no means insecure.
127
128## D2 as a library
129
130In addition to being a runnable CLI tool, D2 can also be used to produce diagrams from
131Go programs.
132
133For examples, see [./docs/examples/lib](./docs/examples/lib). This [blog
134post](https://terrastruct.com/blog/post/generate-diagrams-programmatically/) also demos a
135complete, runnable example of using D2 as a library for a real-world use case.
136
137## Themes
138
139D2 includes a variety of official themes to style your diagrams beautifully right out of
140the box. See [./d2themes](./d2themes) to browse the available themes and make or
141contribute your own creation.
142
143## Fonts
144
145D2 ships with "Source Sans Pro" as the font in renders. If you wish to use a different
146one, please see [./d2renderers/d2fonts](./d2renderers/d2fonts).
147
148## Export file types
149
150D2 currently supports SVG, PNG and PDF exports. More coming soon.
151
152## Language tooling
153
154D2 is designed with language tooling in mind. D2's parser can parse multiple errors from a
155broken program, has an autoformatter, syntax highlighting, and we have plans for LSP's and
156more. Good language tooling is necessary for creating and maintaining large diagrams.
157
158The extensions for VSCode and Vim can be found in the [Related](#related) section.
159
160## Plugins
161
162D2 is designed to be extensible and composable. The plugin system allows you to
163change out layout engines and customize the rendering pipeline. Plugins can either be
164bundled with the build or separately installed as a standalone binary.
165
166**Layout engines**:
167
168- [dagre](https://github.com/dagrejs/dagre) (default, bundled): A fast, directed graph
169 layout engine that produces layered/hierarchical layouts. Based on Graphviz's DOT
170 algorithm.
171- [ELK](https://github.com/kieler/elkjs) (bundled): A directed graph layout engine
172 particularly suited for node-link diagrams with an inherent direction and ports.
173- [TALA](https://github.com/terrastruct/TALA) (binary): Novel layout engine designed
174 specifically for software architecture diagrams. Requires separate install, visit the
175 Github page for more.
176
177D2 intends to integrate with a variety of layout engines, e.g. `dot`, as well as
178single-purpose layout types like sequence diagrams. You can choose whichever layout engine
179you like and works best for the diagram you're making.
180
181## Comparison
182
183For a comparison against other popular text-to-diagram tools, see
184[https://text-to-diagram.com](https://text-to-diagram.com).
185
186## Contributing
187
188Contributions are welcome! See [./docs/CONTRIBUTING.md](./docs/CONTRIBUTING.md).
189
190## License
191
192Open sourced under the Mozilla Public License 2.0. See [./LICENSE.txt](./LICENSE.txt).
193
194## Related
195
196We are constantly working on new plugins, integrations, extensions. Contributions are
197welcome in any official or community plugins. If you have somewhere in your workflow that
198you want to use D2, feel free to open a discussion. We have limited bandwidth and usually
199choose the most high-demand ones to work on. If you make something cool with D2 yourself,
200let us know and we'll be happy to include it here!
201
202### Official plugins
203
204- **VSCode extension**: [https://github.com/terrastruct/d2-vscode](https://github.com/terrastruct/d2-vscode)
205- **Vim extension**: [https://github.com/terrastruct/d2-vim](https://github.com/terrastruct/d2-vim)
206- **Obsidian plugin**: [https://github.com/terrastruct/d2-obsidian](https://github.com/terrastruct/d2-obsidian)
207- **Slack app**: [https://d2lang.com/tour/slack](https://d2lang.com/tour/slack)
208- **Discord plugin**: [https://d2lang.com/tour/discord](https://d2lang.com/tour/discord)
209
210### Community plugins
211
212- **Tree-sitter grammar**: [https://git.pleshevski.ru/pleshevskiy/tree-sitter-d2](https://git.pleshevski.ru/pleshevskiy/tree-sitter-d2)
213- **Emacs major mode**: [https://github.com/andorsk/d2-mode](https://github.com/andorsk/d2-mode)
214- **Goldmark extension**: [https://github.com/FurqanSoftware/goldmark-d2](https://github.com/FurqanSoftware/goldmark-d2)
215- **Telegram bot**: [https://github.com/meinside/telegram-d2-bot](https://github.com/meinside/telegram-d2-bot)
216- **Postgres importer**: [https://github.com/zekenie/d2-erd-from-postgres](https://github.com/zekenie/d2-erd-from-postgres)
217- **Structurizr to D2 exporter**: [https://github.com/goto1134/structurizr-d2-exporter](https://github.com/goto1134/structurizr-d2-exporter)
218- **MdBook preprocessor**: [https://github.com/danieleades/mdbook-d2](https://github.com/danieleades/mdbook-d2)
219- **ROS2 D2 Exporter**: [https://github.com/Greenroom-Robotics/ros-d2](https://github.com/Greenroom-Robotics/ros-d2)
220- **D2 org-mode support**: [https://github.com/xcapaldi/ob-d2](https://github.com/xcapaldi/ob-d2)
221- **Python D2 diagram builder**: [https://github.com/MrBlenny/py-d2](https://github.com/MrBlenny/py-d2)
222- **Clojure D2 transpiler**: [https://github.com/judepayne/dictim](https://github.com/judepayne/dictim)
223- **JavaScript D2 diagram builder**: [https://github.com/Kreshnik/d2lang-js](https://github.com/Kreshnik/d2lang-js)
224- **C# & dotnet SDK**: [https://github.com/Stephanvs/d2lang-cs](https://github.com/Stephanvs/d2lang-cs)
225- **Maven plugin**: [https://github.com/andrinmeier/unofficial-d2lang-maven-plugin](https://github.com/andrinmeier/unofficial-d2lang-maven-plugin)
226- **Confluence plugin**: [https://github.com/andrinmeier/unofficial-d2lang-confluence-plugin](https://github.com/andrinmeier/unofficial-d2lang-confluence-plugin)
227- **CIL (C#, Visual Basic, F#, C++ CLR) to D2**: [https://github.com/HugoVG/AppDiagram](https://github.com/HugoVG/AppDiagram)
228- **D2 Snippets (for text editors)**: [https://github.com/Paracelsus-Rose/D2-Language-Code-Snippets](https://github.com/Paracelsus-Rose/D2-Language-Code-Snippets)
229- **Mongo to D2**: [https://github.com/novuhq/mongo-to-D2](https://github.com/novuhq/mongo-to-D2)
230- **Pandoc filter**: [https://github.com/ram02z/d2-filter](https://github.com/ram02z/d2-filter)
231- **Logseq-D2**: [https://github.com/b-yp/logseq-d2](https://github.com/b-yp/logseq-d2)
232- **ent2d2**: [https://github.com/tmc/ent2d2](https://github.com/tmc/ent2d2)
233- **MkDocs Plugin**: [https://github.com/landmaj/mkdocs-d2-plugin](https://github.com/landmaj/mkdocs-d2-plugin)
234
235### Misc
236
237- **Comparison site**: [https://github.com/terrastruct/text-to-diagram-site](https://github.com/terrastruct/text-to-diagram-site)
238- **Playground**: [https://github.com/terrastruct/d2-playground](https://github.com/terrastruct/d2-playground)
239- **Language docs**: [https://github.com/terrastruct/d2-docs](https://github.com/terrastruct/d2-docs)
240- **Hosted icons**: [https://icons.terrastruct.com](https://icons.terrastruct.com)
241
242## FAQ
243
244- Does D2 collect telemetry?
245 - No, D2 does not use an internet connection after installation, except to check for
246 version updates from Github periodically.
247- Does D2 need a browser to run?
248 - No, D2 can run entirely server-side.
249- What's coming in the next release?
250 - See [./ci/release/changelogs/next.md](./ci/release/changelogs/next.md).
251- I have a question or need help.
252 - The best way to get help is to ask on [D2 Discord](https://discord.gg/NF6X8K4eDq)
253- I have a feature request, proposal, or bug report.
254 - Please open up a Github Issue.
255- I have a private inquiry.
256 - Please reach out at [hi@d2lang.com](hi@d2lang.com).
257
258## Notable open-source projects documenting with D2
259
260Do you have or see an open-source project with `.d2` files? Please submit a PR adding to
261this selected list of featured projects using D2.
262
263- [ElasticSearch](https://github.com/elastic/beats/blob/main/libbeat/publisher/queue/proxy/diagrams/broker.d2)
264- [UC
265 Berkeley](https://github.com/ucb-bar/hammer/blob/2b5c04d7b7d9ee3c73575efcd7ee0698bd5bfa88/doc/Hammer-Use/hier.d2)
266- [Coronacheck](https://github.com/minvws/nl-covid19-coronacheck-app-ios/blob/e1567e9d1633b3273c537a105bff0e7d3a57ecfe/Diagrams/client-side-datamodel.d2)
267 - Official app of the Netherlands for coronavirus entry passes.
268- [Block
269 Protocol](https://github.com/blockprotocol/blockprotocol/blob/db4cf8d422b881e52113aa52467d53115270e2b3/libs/%40blockprotocol/type-system/crate/assets/overview.d2)
270 - The Block Protocol is an open standard for building and using data-driven blocks (1.2k
271 stars).
272- [Dagger](https://github.com/dagger/dagger/tree/main/cmd/dagger-graph)
273 - A programmable CI/CD engine that runs your pipelines in containers (8k stars).
274- [Ivy
275 Wallet](https://github.com/Ivy-Apps/ivy-wallet/blob/8062624bfa65175ec143cdc4038de27a84d38b57/assets/calc_algo.d2)
276 - Open-source money manager app for Android (1.1k stars).
277- [LocalStack](https://docs.localstack.cloud/references/network-troubleshooting/)
278 - Cloud service emulator (46k stars)
279- [Queue Library](https://github.com/golang-queue/queue/tree/master/images)
280 - Queue is a Golang library for spawning and managing a Goroutine pool
View as plain text