Is Chiltepin a D2 alternative?

For diagrams that live inside documentation, yes. D2 is a better diagram language: more shapes, containers, classes, imports, three layout engines and a sketch mode. Chiltepin is a documentation system where a diagram is one typed block next to tables, endpoint lists and decision records, and every block is validated against a schema. If the diagram is the deliverable, D2 is the closer fit; if the document is, Chiltepin is.

Can I migrate from D2?

There is no D2 importer. D2 is expressive enough that a faithful converter would lose most of what makes it worth using, so we have not built one. Hand the diagram or its description to your agent, let the skill write the block, and run chiltepin check. Keep the D2 files for anything Chiltepin cannot express.

Which layout engine does Chiltepin use?

Its own, inside the renderer, and it is not configurable. Each block type has one layout: a sequence block places lifelines in actor order, a flow block uses a grid, a C4 block nests containers. The point is that the same source always draws the same picture, in CI, in the site and in the PDF. D2 gives you dagre, ELK and TALA and lets you pin directions and positions; if you need that, D2 is the right tool.

Can I theme Chiltepin output like D2?

Not in the same way. D2 ships themes, dark mode and a sketch mode you switch with a flag. Chiltepin has one editorial skin with one accent colour, and it is applied to every block so a document reads as one thing. That is a deliberate constraint, and it is a real loss if you want your diagrams to match a brand or look hand-drawn.

How reliably does an AI agent write Chiltepin blocks?

In our own generation eval (40 scenarios, September 2026) an agent with the skill picked the right block 39.5 times out of 40, 33 of 40 documents were clean on the first write, all 40 were clean at handoff and none failed to render, at about 55K tokens and 91 seconds per document. The harness is in the product repository under evals. We have not run the same eval on D2, and its compiler checks syntax rather than content, so the numbers would not be comparable.

Comparison

Chiltepin vs D2: layout engines or schemas

D2 is the best-designed diagram language of the last few years. It is declarative and readable, has a formatter, a watch mode and a playground, first-class SQL tables and classes, containers, imports and variables, three layout engines including the commercial TALA, themes, dark mode, a sketch mode and animated output. It is a diagram tool, and a very good one. Chiltepin is a documentation system: the diagram is one typed block in a Markdown file, the schema says what the block may contain, chiltepin check enforces it in CI, and the same grammar covers the tables, endpoints and decisions around the diagram.

Side by side

	D2	Chiltepin
Source format	The D2 language in .d2 files: declarative, with classes, imports, variables and d2 fmt	Markdown with typed YAML blocks, one grammar for every block type
Who draws the layout	A choice of engines: dagre, ELK, or TALA (commercial); the author can pin positions and directions	The renderer, from the data; no engine choice, no coordinates in the source
Where it renders	The d2 binary (Go), locally or in CI, with a watch mode and a hosted playground	The CLI (Node) or the browser Studio; output is static SVG and HTML
Validation in CI	The compiler rejects bad syntax and unknown keywords; no schema for the content	`chiltepin check` validates fields, references and ids against a strict schema and exits non-zero
Beyond diagrams	Diagrams only, but rich ones: SQL tables, classes, sequence, grids, Markdown and code inside shapes	Tables, API endpoints, ADRs, threat models, charts and decks in the same files and validator
AI agent workflow	The model writes D2 from memory; the compiler catches syntax, not meaning	A skill the agent installs; it writes YAML, runs the validator and repairs diagnostics before handoff
Output formats	SVG, PNG, PDF, PPTX, GIF animations; themes, dark mode and a hand-drawn sketch mode	Static site, standalone HTML, slides, PDF per document; one editorial look, no themes
Ecosystem / tooling	Growing fast: editor extensions, a playground, Kroki support, Terrastruct behind it	Newer and smaller: CLI, Studio, one agent skill; no D2 importer
Licence	MPL-2.0 for D2; TALA is closed-source and paid	MIT
Best for	One large, polished diagram with control over its layout and look	Documents an agent writes and CI checks, with diagrams as one block among several

The same diagram, both ways

A login flow: the browser posts to the auth service, which sends the user through Google and comes back with a session cookie. In D2:

shape: sequence_diagram
browser: Browser
auth: Auth service
google: Google

browser -> auth: POST /login
auth -> google: Redirect to consent
google -> auth: Authorization code
auth -> google: Exchange code for ID token
auth -> browser: Session cookie

Five messages, three actors, laid out by whichever engine you pass to d2. There is no importer for this text; an agent with the skill rewrites it as a sequence block in a few lines of YAML. The Chiltepin form of a sequence block renders in the example section below.

When to pick D2

Pick D2 when the diagram is the product: a large system map you will iterate on, where you want to choose the layout engine, pin a direction, nest containers three deep, style shapes by class, and export it in the sketch theme for a slide. D2 gives the author control over appearance that Chiltepin deliberately withholds, and its language is nicer to write by hand than YAML. If you are choosing a diagram-as-code tool and not a documentation system, D2 is a strong choice.

When to pick Chiltepin

Pick Chiltepin when the diagram is one block of many and the document has to pass review like code: chiltepin check on every pull request, one look across the site, the deck and the PDF, and an agent that writes the whole file with something to validate against. In our own generation eval (40 scenarios, September 2026) an agent with the skill delivered 40 of 40 documents clean at handoff with no render failures; the harness is in the repository. You give up layout engines and themes; you get a schema and a document.

What a Chiltepin block looks like

This is the sequence starter template: two actors, a request, and an alt frame with two outcomes. D2 writes a sequence diagram as shapes and connections; Chiltepin writes it as actors and messages, and the schema rejects anything else.

```sequence
id: seq-example
actors:
  - { id: Client, name: Client }
  - { id: Server, name: Server }
messages:
  - Client -> +Server: request
  - alt: cache hit
  - Server --> -Client: 200 cached
  - else: miss
  - Server --> -Client: 200 fresh
  - end
```

SECTION 01 · Sequence

SEQUENCE

Legendcallresponsethe answer the caller getsfragment (alt / opt / loop)active

A sequence block from typed YAML. Activation bars, the frame and the arrowheads are decided by the renderer at build time.

Every block on this site is rendered this way, at build time, by the same pipeline chiltepin build runs. See the block catalog or the documents an agent wrote. Other comparisons: vs Mermaid, vs PlantUML, vs Eraser, vs Structurizr, vs Archify.

Frequently asked questions

Is Chiltepin a D2 alternative?: For diagrams that live inside documentation, yes. D2 is a better diagram language: more shapes, containers, classes, imports, three layout engines and a sketch mode. Chiltepin is a documentation system where a diagram is one typed block next to tables, endpoint lists and decision records, and every block is validated against a schema. If the diagram is the deliverable, D2 is the closer fit; if the document is, Chiltepin is.
Can I migrate from D2?: There is no D2 importer. D2 is expressive enough that a faithful converter would lose most of what makes it worth using, so we have not built one. Hand the diagram or its description to your agent, let the skill write the block, and run chiltepin check. Keep the D2 files for anything Chiltepin cannot express.
Which layout engine does Chiltepin use?: Its own, inside the renderer, and it is not configurable. Each block type has one layout: a sequence block places lifelines in actor order, a flow block uses a grid, a C4 block nests containers. The point is that the same source always draws the same picture, in CI, in the site and in the PDF. D2 gives you dagre, ELK and TALA and lets you pin directions and positions; if you need that, D2 is the right tool.
Can I theme Chiltepin output like D2?: Not in the same way. D2 ships themes, dark mode and a sketch mode you switch with a flag. Chiltepin has one editorial skin with one accent colour, and it is applied to every block so a document reads as one thing. That is a deliberate constraint, and it is a real loss if you want your diagrams to match a brand or look hand-drawn.
How reliably does an AI agent write Chiltepin blocks?: In our own generation eval (40 scenarios, September 2026) an agent with the skill picked the right block 39.5 times out of 40, 33 of 40 documents were clean on the first write, all 40 were clean at handoff and none failed to render, at about 55K tokens and 91 seconds per document. The harness is in the product repository under evals. We have not run the same eval on D2, and its compiler checks syntax rather than content, so the numbers would not be comparable.

Try Studio demo Set up your agentnpx skills add jdiejim/chiltepin -y