text-to-diagram.com: the same diagram written four ways, side by side

A comparison site, and the bias it declares

text-to-diagram.com compares syntax, layouts and outputs between languages for generating diagrams with text, and the site's own framing is unusually direct about the fact that one of the four languages has an interest in the outcome.

The full disclosure paragraph says the site and D2 were originally created at Terrastruct, that today the site is maintained by the independent D2 project fiscally sponsored by Hack Club, that D2 appears first, and that otherwise it gets no special treatment. It goes further: contributions and corrections are welcome, even ones that make D2 look bad, and they will be included without bias, and then the project will furiously improve D2.

That is worth reading carefully as a reader of the site, and it is also worth reading as a signal about the project. A comparison site that admits its bias and asks for corrections anyway is more useful than one that presents itself as neutral, because at least you know where the leaning is. The order of the tabs is the most visible form of that bias, and it is the one thing a reader should keep in mind when scrolling.

The project behind it is the D2 project, whose homepage for this repository is text-to-diagram.com itself, and the topic list is diagram, diagrams, dsl, software-architecture and text-to-diagram. The primary language is TypeScript, the licence is GPL-3.0, the default branch is master, and the last push was on 2026-10-06. The repository has no GitHub releases, and the readme carries a CI badge, a daily workflow badge, a licence badge and a Vercel open-source programme badge.

The README itself is unusually short for a site of this kind, because the site is the product. The FAQ lives at a fragment on the site itself, and the readme points there rather than repeating it.

Four languages, chosen for popularity

The set of compared languages is D2, Mermaid, GraphViz and PlantUML.

The readme explains the selection criterion, and it is a candid one. High-quality comparisons take a lot of work, which will only get more as the number of examples grows, and other than D2 the currently supported set are what seem to be the most popular tools for text-to-diagram.

So the coverage is four languages out of a much larger field, chosen by reach rather than by merit. For completeness, the readme points to xosh.org/text-to-diagram as the best catalogue it has found, which is the honest thing to do and the place to look if your language is not in the four.

Each of the four has a distinct profile, which is what makes the comparison interesting rather than decorative.

D2 is the language of the project that maintains the site, and it is a DSL in its own right rather than a rendering frontend for something else. Mermaid is the browser-oriented one, where the diagram is usually defined in a Markdown-adjacent block that a renderer turns into SVG. GraphViz is the graph theory one, with the DOT language and the dot layout engine behind it. PlantUML is the general-purpose modelling one, covering sequence diagrams, class diagrams and the UML family.

The comparison the site offers is therefore across genuinely different approaches: a dedicated diagram language, a documentation-friendly embeddable syntax, a graph layout tool, and a modelling notation. That is a more useful axis of comparison than four syntaxes of the same thing.

The feature matrix is a specific React component in the source tree, src/components/Features.tsx, and the readme asks that a significant feature worth comparing be added as a line there. That file is the spine of the comparison, and it is worth reading directly if you want to know what dimensions the site actually compares.

Examples as data, with renders checked into the repository

The example structure is the part that explains how the site works, and it is the part a contributor has to follow.

Each example is a folder in src/examples with a short name. Inside it there is a description.txt to describe what the example aims to demonstrate, a render/ directory for the SVG renders, and a syntax/ directory for the texts. And if there are languages with errors for this example, an error/ directory holds those.

That error directory is a detail that tells you what the site is actually for. Most comparison sites show you what each tool does well. This one records where each tool fails on the same input, which is the information you need when you are choosing a language and the language has to survive the diagram you actually need to draw.

The generation step is a shell script.

# Only needed first run
git submodule update --init --recursive
npx --yes [email protected] -- yarn install --frozen-lockfile

npx --yes [email protected] -- yarn dev

And the renders are produced by running ./ci/render.sh with the respective tools installed, where the prerequisites are mermaid-cli which provides mmdc, plantuml, graphviz which provides dot, and d2 itself. So the site is not a live comparison service. It is a static site whose SVG outputs are generated once by running four real diagram tools and committed to the repository.

That architecture has an important consequence stated plainly in the readme: the checked-in examples are already rendered, and production builds do not need D2, Mermaid, Graphviz or PlantUML. No application server or production environment secrets are required.

The consequence for a reader is that the comparisons are curated rather than live. You are looking at the maintainers' chosen examples with their chosen settings, and the tradeoff for that is that the site is fast, works offline, and does not degrade when a tool's version changes underneath it.

Adding an example is explicitly allowed to be incomplete. The instruction is to create the text for as many languages as you can, and to say it is okay if not totally complete, because the maintainers or others can fill it in.

Running the site locally, and how it is hosted

The local development instructions are short, and they use a pinned Yarn through npx rather than assuming you have a particular version installed.

git submodule update --init --recursive
npx --yes [email protected] -- yarn install --frozen-lockfile
npx --yes [email protected] -- yarn dev

The submodule step is needed because the extensions directory holds a git submodule for the D2 VS Code extension, which the typecheck script also initialises explicitly before running tsc.

The dev script runs next dev -p 9000, so the local site is on port 9000. The build script is next build, then next-sitemap with its own config, then next export.

Production hosting is Vercel, and the readme is unusually specific about how it is configured, which is a useful record for anyone who ends up maintaining it. Vercel builds the master branch as a static site for text-to-diagram.com and www.text-to-diagram.com, using Node.js 24 and Yarn 1.22.22, with both public Git submodules initialized before building.

git submodule update --init --recursive
npx --yes [email protected] -- yarn install --frozen-lockfile
npx --yes [email protected] -- yarn build

The existing build exports out/, including index.html, 404.html, the sitemap, the robots file and browser assets. The vercel.json settings select Other as the framework and out as the output, and the guidance is to choose a fixed Standard build machine, disable on-demand concurrency, and require the existing GitHub checks ci and nofixups before assigning production domains.

Two details in the domain configuration are the kind of thing that causes a support ticket if left to defaults. The www domain is configured to redirect to the apex with status 301 explicitly, because Vercel's default domain redirect status is 308, and the project setting is required alongside the redirect intent declared in vercel.json. And there is no catch-all rewrite to index.html, so missing paths must keep a 404 status.

The rollback plan, and the migration away from CloudFront

The readme contains a hosting rollback procedure, and its existence is itself information about how the project is run.

For an application regression, the guidance is to promote the previous working Vercel deployment. For a hosting rollback, the steps are to pause automatic Vercel deployments, re-enable the retained CloudFront distribution through a reviewed Terraform change, wait for it to show Deployed, and restore its former DNS aliases, then verify HTTPS and redirects after DNS convergence. The AWS deployment job is retired and the instruction is not to restore it while Vercel owns production.

So the project has a two-provider arrangement during a migration window: Vercel owns production, and the former CloudFront distribution and its S3 bucket are kept through the rollback window. The DNS and retained AWS rollback resources are managed in d2lang/infra, and the readme says to review and apply that repository's migration plan separately.

The reason a rollback window exists at all is a bug the readme documents, and it is a good illustration of why hosting details deserve this much attention. The former CloudFront function double-encoded already escaped query values, so the domain redirect now uses Vercel's default response headers instead, and its 301 retains the original path and query including repeated query parameters.

There is also a pre-flight checklist for DNS changes, which is the kind of list that saves a long debugging session: verify both hostnames, a missing path, /404, /404.html, representative CSS, JavaScript and WASM and images, /js/script.js, and /api/event.

The last piece is the analytics. The vercel.json preserves the static 404, the current security headers, the Plausible script and event proxies, and the browser cache lifetimes on apex pages, assets and proxy responses. The site proxies the Plausible script and event calls through its own domain, which is consistent with a project that publishes a bias disclosure and asks for corrections rather than a marketing funnel.

Editorial conclusion

text-to-diagram.com fits a developer picking between D2, Mermaid, GraphViz and PlantUML who wants to see the same diagram in each before reading four manuals, and it does not fit someone looking for a diagram editor, a live renderer or a catalogue of every diagram tool, since it covers four languages and points elsewhere for the rest. Before drawing a conclusion from the examples, note the stated bias policy: D2 appears first, the site is maintained by the independent D2 project with funding from Hack Club, and contributions that make D2 look bad are welcome and will be included.

Frequently asked questions

Official sources

1. d2lang/text-to-diagram-site on GitHub
2. Issues
3. License: GPL-3.0
4. Project website
5. README