Skip to content

README.md

Latest commit

 

History

History
142 lines (108 loc) · 5.93 KB

README.md

File metadata and controls

142 lines (108 loc) · 5.93 KB
Raw

Text to diagram comparisons

Go to comparisons site

Compare syntax, layouts, outputs between languages for generating diagrams with text.

Screen Shot 2022-10-22 at 3 57 45 PM

ci daily license

Vercel OSS Program

Full disclosure: This site and D2 were originally created at Terrastruct. Today, the site is maintained by the independent D2 project, fiscally sponsored by Hack Club. D2 appears first; otherwise, it gets no special treatment. Contributions and corrections are welcome—even ones that make D2 look bad. We'll include them without bias and then furiously improve D2.

Currently supported comparisons

High-quality comparisons take a lot of work, which will only get more as the number of examples grows. Other than D2, the currently supported set are what seem to be the most popular tools for text-to-diagram.

  • D2
  • Mermaid
  • GraphViz
  • PlantUML

For completeness, you may want to also evaluate less popular tools/languages. The best catalog we've found is https://xosh.org/text-to-diagram/.

FAQ

Contributing

Run locally

# Only needed first run
git submodule update --init --recursive
npx --yes --package=yarn@1.22.22 -- yarn install --frozen-lockfile

npx --yes --package=yarn@1.22.22 -- yarn dev

Production hosting

Vercel builds the master branch as a static site for text-to-diagram.com and www.text-to-diagram.com. Use Node.js 24 and Yarn 1.22.22. Initialize both public Git submodules before building, then run:

git submodule update --init --recursive
npx --yes --package=yarn@1.22.22 -- yarn install --frozen-lockfile
npx --yes --package=yarn@1.22.22 -- yarn build

The existing build exports out/, including index.html, 404.html, the sitemap, robots file, and browser assets. The checked-in examples are already rendered; production builds do not need D2, Mermaid, Graphviz, or PlantUML. No application server or production environment secrets are required.

Import this repository into the D2 Vercel team as text-to-diagram. The vercel.json settings select Other as the framework and out as the output. Choose a fixed Standard build machine, disable on-demand concurrency, and require the existing GitHub checks ci and nofixups before assigning production domains. Keep the public PR and daily workflows enabled.

Add both custom domains in the project's Domains settings. Configure www.text-to-diagram.com to redirect to text-to-diagram.com and select status 301 explicitly; Vercel's default domain redirect status is 308. This project setting is required alongside the redirect intent declared in vercel.json.

vercel.json preserves the static 404, current security headers, Plausible script/event proxies, and browser cache lifetimes on apex pages, assets, and proxy responses. The domain redirect uses Vercel's default response headers. Its 301 retains the original path and query, including repeated query parameters. This corrects the former CloudFront function, which double-encoded already escaped query values. There is no catch-all rewrite to index.html: missing paths must keep a 404 status.

Before changing DNS, verify both hostnames, a missing path, /404, /404.html, representative CSS/JavaScript/WASM and images, /js/script.js, and /api/event. The DNS and retained AWS rollback resources are managed in d2lang/infra; review and apply that repository's migration plan separately. Keep the former S3 bucket and CloudFront distribution through the rollback window.

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

Adding examples

Please follow the examples in src/examples.

  1. Create a folder in src/examples with a short name of the example
  2. Add in that folder:
  • description.txt to describe what the example aims to demonstrate.
  • render/ for SVG renders
  • syntax/ for texts
  • If there are languages with errors for this example, error/
  1. Create the text for as many languages as you can. It's okay if not totally complete. We or others can fill.
  2. Run ./ci/render.sh (with the respective tools installed)
  • Pre-requisite tools:
    • mermaid-cli (mmdc)
    • plantuml
    • graphviz (dot)
    • d2

CLI render

Adding features

If you think there's a significant feature that people want to compare against, feel free to add a line in src/components/Features.tsx.

Adding languages

If you wish to add a new language, please fill out as many of the examples and features as possible. It's a lot of work, but if there's enough interest in the language, perhaps others will help out.