d2

command module
v0.4.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: May 2, 2023 License: MPL-2.0 Imports: 2 Imported by: 1

README

Table of Contents

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.

D2 render example

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. This blog post also demos a complete, runnable example of using D2 as a library for a real-world use case.

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, PNG and PDF 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.

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
Community plugins
Misc

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.

Notable 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 selected list of featured projects using D2.

  • ElasticSearch
  • UC Berkeley
  • Coronacheck
    • Official app of the Netherlands for coronavirus entry passes.
  • Block Protocol
    • The Block Protocol is an open standard for building and using data-driven blocks (1.2k stars).
  • Dagger
    • A programmable CI/CD engine that runs your pipelines in containers (8k stars).
  • Ivy Wallet
    • Open-source money manager app for Android (1.1k stars).
  • LocalStack
    • Cloud service emulator (46k stars)
  • Queue Library
    • Queue is a Golang library for spawning and managing a Goroutine pool
  • ent2d2
    • A project to render entity relation (ER) diagrams for the Ent ORM.

Documentation

The Go Gopher

There is no documentation for this package.

Directories

Path Synopsis
cmd
TODO: Remove boxes and cleanup like d2ir
TODO: Remove boxes and cleanup like d2ir
Package d2compiler implements a parser, compiler and autoformatter for the Terrastruct d2 diagramming language.
Package d2compiler implements a parser, compiler and autoformatter for the Terrastruct d2 diagramming language.
Package d2ir implements a tree data structure to keep track of the resolved value of D2 keys.
Package d2ir implements a tree data structure to keep track of the resolved value of D2 keys.
d2layouts
d2elklayout
d2elklayout is a wrapper around the Javascript port of ELK.
d2elklayout is a wrapper around the Javascript port of ELK.
d2near
d2near applies near keywords when they're constants Intended to be run as the last stage of layout after the diagram has already undergone layout
d2near applies near keywords when they're constants Intended to be run as the last stage of layout after the diagram has already undergone layout
Package d2plugin enables the d2 CLI to run functions bundled with the d2 binary or via external plugin binaries.
Package d2plugin enables the d2 CLI to run functions bundled with the d2 binary or via external plugin binaries.
d2renderers
d2fonts
TODO write a script to do this as part of CI Currently using an online converter: https://dopiaza.org/tools/datauri/index.php
TODO write a script to do this as part of CI Currently using an online converter: https://dopiaza.org/tools/datauri/index.php
d2svg
d2svg implements an SVG renderer for d2 diagrams.
d2svg implements an SVG renderer for d2 diagrams.
d2themes defines themes to make d2 diagrams pretty Color codes: darkest (N1) -> lightest (N7)
d2themes defines themes to make d2 diagrams pretty Color codes: darkest (N1) -> lightest (N7)
docs
e2etests
lib
env
geo
log
Package log is a context wrapper around slog.Logger
Package log is a context wrapper around slog.Logger
pdf
png
pptx
pptx is a package to create slide presentations in pptx (Microsoft Power Point) format.
pptx is a package to create slide presentations in pptx (Microsoft Power Point) format.
svg
xgif
xgif is a helper package to create GIF animations based on PNG images The resulting animations have the following properties: 1.
xgif is a helper package to create GIF animations based on PNG images The resulting animations have the following properties: 1.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL