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 — week three and the emphasis becomes **2.4 metres**.

Nodes: structure where you ask for it

A node is a named structure. Write it as (name … name) on one line, or as @name … name@ around a block of lines. Headings, lists, tables, figures, asides, and sections are built in — you use them with no setup. Everything outside a node stays prose. Nodes & the mental model lists the full set.

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. Lists of records — a table of readings, a bibliography, a cast of characters — work the same way, with loops to lay them out.

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. Write with the wit command and you never see the packages; embed the packages in your own program and you never touch the command line.

What Wit is not