Is Chiltepin a Mermaid alternative?

For diagrams inside longer documents, yes. Both put the diagram in a fenced block in Markdown. Mermaid draws it in the browser wherever the platform supports it. Chiltepin validates it against a schema and draws it at build time, next to tables, endpoint lists and decision records written the same way. If you need a diagram that GitHub renders in a README with no build step, Mermaid is the shorter path.

Can I migrate from Mermaid?

For the supported subset, yes, without rewriting. Chiltepin parses a mermaid fence whose first line is sequenceDiagram, flowchart or graph, erDiagram, stateDiagram or pie and converts it into the typed block. The result validates and renders like a hand-written block, and the first structured edit writes it back as YAML. Other Mermaid grammars stay as plain code blocks and are never flagged. Subgraph framing, composite states and rect boxes are dropped; the messages and nodes inside are kept.

Why does Chiltepin render at build time instead of in the browser?

So the output is the same everywhere. A Mermaid diagram depends on the Mermaid version the viewing platform ships, and two wikis can draw the same source differently. Chiltepin renders once, from the data, into static SVG; the site, the PDF and the slide deck all show the same picture and the reader’s page runs no JavaScript for it.

Does Chiltepin cover the same diagram types as Mermaid?

The common ones: sequence, flowchart, state, ER, C4, Gantt, git graph, timeline, quadrant, Sankey, pie and donut. Mermaid has a few grammars Chiltepin does not. Chiltepin has block families Mermaid does not attempt: API endpoints, ADRs, threat models, wireframes, decks. Check the block catalog for the current list.

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 and the scenarios are in the product repository under evals. We have not measured the same thing for Mermaid, and a free-form DSL has no validator to score against.

Comparison

Chiltepin vs Mermaid: runtime or build time

Mermaid is the default for a reason. You type a short DSL in a fenced block and GitHub, GitLab, Notion, Obsidian and most wikis draw it with no build step. It covers about twenty diagram types, has a live editor, plugins for nearly every editor, and years of answered questions. Chiltepin keeps the fence-in-Markdown idea and moves the work to build time: the block is typed YAML with a schema, chiltepin check proves it right in CI, and the renderer draws it once into static SVG. This page is the head-to-head; the migration path is on the Mermaid alternative page.

Side by side

	Mermaid	Chiltepin
Source format	A text DSL per diagram type, in a fenced code block	Markdown with typed YAML blocks; a Mermaid fence in the same file converts automatically
Who draws the layout	dagre or ELK in the browser, at view time	The renderer, at build time; no coordinates in the source
Where it renders	Natively in GitHub, GitLab, Notion, Obsidian and most wikis; a JS runtime on every page	Static SVG and HTML from the CLI or Studio; nothing runs on the reader’s page
Validation in CI	None; a diagram is valid if it parses	`chiltepin check` validates every block against a strict schema, checks references and ids, and exits non-zero
Beyond diagrams	Diagrams only; the rest of the document is plain Markdown	Tables, API endpoints, ADRs, threat models, charts and decks share the same grammar and validator
AI agent workflow	Prompt the model and read the result; nothing to check the output against	A skill your agent installs; it writes the YAML, runs the validator and fixes diagnostics before handoff
Output formats	SVG or PNG through the CLI; otherwise wherever the fence is embedded	Static site, standalone HTML, slides, PDF from one source
Ecosystem / tooling	Huge: about twenty diagram types, a live editor, plugins for most editors and wikis	Smaller and newer: CLI, browser Studio, one agent skill, a mermaid input dialect
Licence	MIT	MIT
Best for	One diagram where Markdown already renders, with zero setup	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 Mermaid:

sequenceDiagram
  participant B as Browser
  participant A as Auth service
  participant G as Google
  B->>A: POST /login
  A->>G: Redirect to consent
  G-->>A: Authorization code
  A->>G: Exchange code for ID token
  A-->>B: Session cookie

Five messages, three participants, rendered by whichever Mermaid build the page ships. Paste this fence into a Chiltepin document and it converts into a sequence block on parse; the Chiltepin form of a sequence block renders in the example section below.

When to pick Mermaid

Pick Mermaid when the diagram lives where Mermaid already renders and that is the whole job: a flowchart in a README, a sequence in a pull request description, a state machine in a Notion page. There is nothing to install, the syntax is short, and every teammate has seen it before. If your documents are diagrams and prose only, and the platform draws them for free, Mermaid is the right call and we would use it too.

When to pick Chiltepin

Pick Chiltepin when the diagram is one block in a document that also holds the endpoint table, the decision record and the threat register, and you want all of it validated on every pull request and rendered the same in the site, the deck and the PDF. It matters most when an agent is the author: a schema gives it something to check 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. Your existing Mermaid fences come along for the supported grammars.

What a Chiltepin block looks like

This is the sequence starter template: two actors, a request, and an alt frame with two outcomes. The message lines read like Mermaid’s. The differences are the required id, the named actor list, and the schema behind every field.

```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 PlantUML, vs D2, vs Eraser, vs Structurizr, vs Archify.

Frequently asked questions

Is Chiltepin a Mermaid alternative?: For diagrams inside longer documents, yes. Both put the diagram in a fenced block in Markdown. Mermaid draws it in the browser wherever the platform supports it. Chiltepin validates it against a schema and draws it at build time, next to tables, endpoint lists and decision records written the same way. If you need a diagram that GitHub renders in a README with no build step, Mermaid is the shorter path.
Can I migrate from Mermaid?: For the supported subset, yes, without rewriting. Chiltepin parses a mermaid fence whose first line is sequenceDiagram, flowchart or graph, erDiagram, stateDiagram or pie and converts it into the typed block. The result validates and renders like a hand-written block, and the first structured edit writes it back as YAML. Other Mermaid grammars stay as plain code blocks and are never flagged. Subgraph framing, composite states and rect boxes are dropped; the messages and nodes inside are kept.
Why does Chiltepin render at build time instead of in the browser?: So the output is the same everywhere. A Mermaid diagram depends on the Mermaid version the viewing platform ships, and two wikis can draw the same source differently. Chiltepin renders once, from the data, into static SVG; the site, the PDF and the slide deck all show the same picture and the reader’s page runs no JavaScript for it.
Does Chiltepin cover the same diagram types as Mermaid?: The common ones: sequence, flowchart, state, ER, C4, Gantt, git graph, timeline, quadrant, Sankey, pie and donut. Mermaid has a few grammars Chiltepin does not. Chiltepin has block families Mermaid does not attempt: API endpoints, ADRs, threat models, wireframes, decks. Check the block catalog for the current list.
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 and the scenarios are in the product repository under evals. We have not measured the same thing for Mermaid, and a free-form DSL has no validator to score against.

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