A language for diagrams, plots, and drawings.

Start · Language · Examples · Tour · Specification

Etchl lets you describe a drawing in text and render it as SVG, PNG, or an editable Excalidraw scene. It handles text measurement, layout, connector routing, and mathematical curves, so most drawings do not need hand-picked coordinates.

Start with one shape

An Etchl file can be this small:

diagram "Hello" {
  message: rectangle "Hello"
}

Save it as hello.etchl, then render it:

etchl build hello.etchl -o hello.svg

Choose the output with its file extension:

etchl build hello.etchl -o hello.svg
etchl build hello.etchl -o hello.png
etchl build hello.etchl -o hello.excalidraw

SVG and PNG are fixed renders. Excalidraw output uses native shapes that you can edit by hand. Without -o, the CLI currently writes an .excalidraw file beside the source.

Install from the repository

Etchl requires Node.js 22.18 or newer.

git clone https://github.com/fractalops/etchl.git
cd etchl
npm install
npm link

Build with relationships

Give each element a name, then connect those names. An arrangement chooses the positions and leaves room for the connector labels.

diagram "Request flow" {
  arrange grid { columns = 3; gap = 120 }

  browser: ellipse "Browser"
  api: rectangle "API"
  store: rectangle "Database"

  browser -> api "requests"
  api -> store "queries"
}

browser, api, and store are stable IDs. Their quoted text appears in the drawing. Change a label and Etchl measures it again before arranging the diagram.

Structure uses the same nesting you see on the page:

diagram "A small system" {
  client: ellipse "Client"

  platform: frame "Platform" {
    arrange row { gap = 100 }

    api: rectangle "API"
    store: rectangle "Orders"
    api -> store "writes"
  }

  client -> platform.api "calls"
}

The frame owns api and store, so their full names are platform.api and platform.store. No coordinates are needed.

Four small examples

Each picture below is built from the linked Etchl file. The sources are short and independent, so you can copy one without bringing along the others.

Architecture

The architecture library supplies people, systems, containers, and data stores. The layered arrangement derives direction from their relationships.

Source · etchl build examples/readme-architecture.etchl -o architecture.svg

Plot on a coordinate plane

Plots inside math.plane share axes and a viewport. Here the x interval is written once; Etchl infers the vertical interval from sin(x) and cos(x).

Source · etchl build examples/readme-plane.etchl -o plane.svg

Mathematical formulas

Formula source is ordinary TeX. Etchl typesets it once and carries the resulting asset in the drawing plan.

Source · etchl build examples/formulas.etchl -o formulas.svg

A small drawing

This flower uses four curves: a stem, a leaf, seven petals, and a circular centre. The leaf and flower head attach to points along the sampled stem, so moving or reshaping the stem keeps the drawing joined.

Source · etchl build examples/readme-flower.etchl -o flower.svg

Explore when you need more

• The language syntax is the compact reference for source structure, values, references, connections, layout, and reuse.
• The language tour introduces layouts, styles, templates, repetition, measured placement, mathematical plots, formulas, tables, code, images, and annotations.
• Plotting with Etchl covers curve precision, finite series, and the sampler's limits.
• examples/ contains complete sources you can build and modify.
• The specification defines the grammar and processing rules.
• The architecture guide follows a document through parsing, validation, layout, and rendering.

Build and inspect drawings

etchl build drawing.etchl -o drawing.svg
etchl build drawing.etchl -o drawing.png
etchl build drawing.etchl -o drawing.excalidraw
etchl check drawing.etchl

build compiles and renders a drawing. check runs the same compiler without writing one, then reports bounds, paths, connector-label placement, container slack, constraints, and asset sizes. Its default report is readable text; use --format json for machine-readable output. Both commands accept a file, standard input, or inline source with -e.

Excalidraw integration

The Excalidraw output remains editable as native shapes. list, pull, and apply also work with hosted Excalidraw+ scenes and use the EXCALIDRAW_API_KEY environment variable. See Hosted scenes for addresses, replacement, and targeted patches.

Run etchl --help for the complete command reference.

Development

npm run build
npm run typecheck
npm test
npm run test:browser

See Architecture for the compiler structure and Releasing Etchl for the maintainer workflow.

Etchl uses ELK, Shiki, MathJax, Perfect Freehand, and resvg-js. Its editable-scene adapter uses Excalidraw. Etchl is available under the MIT License.