Wit

What is Wit?

Wit is a plain-text markup language for documents. Ordinary sentences render as ordinary paragraphs. When you need a heading, a list, a table, a figure, or a citation, you add a node for that one thing, and the rest of the text stays as it was. One source file compiles to HTML, Markdown, or print-ready PDF.

A first look

This is a complete document. The only markup is the part that isn't prose:

@h1 Field notes — week three h1@

The tide gauge read *2.4 metres* at dawn, higher than any
figure in the log.

@figure
  @img |src ./gauge.png| |alt The tide gauge at dawn|
  @figcaption Thursday's reading, before the wind turned. figcaption@
figure@

Compile it to HTML and you get an <h1>, a paragraph carrying a <strong>, and a real <figure> with its <figcaption>. Compile the same source to Markdown and the heading becomes # Field notes and the emphasis becomes *2.4 metres*.

Nodes: structure where you ask for it

A node is a named structure, written @name … name@. Headings, lists, tables, figures, asides, and sectioning are built in — you use them with no setup, and the renderer decides whether each is a block or an inline span. Everything outside a node stays prose. The full set is in Nodes and core vocabulary.

Data, when a document repeats itself

A fact can live as data instead of being retyped. A record is { key - value }; pull a field into a sentence with @name.field:

source
#station: { name - Ledbury Point, keeper - A. Vane }

Readings this week come from @station.name, logged by @station.keeper.
result

Readings this week come from Ledbury Point, logged by A. Vane.

That renders Readings this week come from Ledbury Point, logged by A. Vane. Write the fact once and reference it wherever it belongs. When a document has to assemble itself from a list of records — a table of readings, a bibliography, a cast of characters — collections and iteration handle that too; the mental model shows how prose, nodes, data, and logic stack up.

What ships

Wit is five zero-dependency TypeScript packages — the parser, the runtime, an HTML renderer, a Markdown renderer, and the wit command-line tool — plus a VS Code extension. A clean install pulls in nothing else. Write with the wit command and you need never see the packages; embed the packages in your own program and you need never touch the command line.

What Wit is not

Wit is a file format, not a content-management system, an editor, or a general templating engine. It is deliberately not Turing-complete: there are conditionals and loops for shaping a document from its data, and one scripting block as the explicit escape hatch for anything more. It is also young — the syntax is stable enough to write a book in, but the ecosystem is small. For fine typesetting control over kerning and page floats, reach for LaTeX; to write in plain text and add structure only where you need it, reach for Wit.

See also