Wit

Wit is a prose-first markup language for people who write — and the systems that consume what they write. Documents read like normal text; structure (nodes, data, conditionals, iteration, scripting) layers in only where the author needs it.

Why Wit?

Markdown is great for prose but breaks the moment you need structure: captioned figures, cross-referenced citations, conditional sections, loops over data. The usual answer is "drop into HTML" or "use a static site generator with frontmatter" — both shred the prose flow.

Wit keeps prose readable while making structure first-class. Plain sentences stay plain. When you need a heading, a citation that resolves itself, a table built from a data record, or a bibliography that gathers contributions from every file in your project, the syntax appears only where it's needed.

The reference implementation ships as five small TypeScript packages (parser, runtime, two renderers, a CLI) plus a VS Code language extension. Zero runtime dependencies.

A taste

reference wit/paper

(title Why I like lighthouses title)
(author T. Greig author)

#weil: Weil, _Gravity and Grace_ (1952) !!

Lighthouses signal *safety* across the _darkest_ nights. Attention, as
@weil argued, is a moral act.

#keepers: [{ name: Mary Bennett, years: 1859–1865 }, { name: R. Ross, years: 1865–1891 }] !!

(ul
(each @keepers as k)
(li @k.name, @k.years li)
(end)
ul)

…builds to HTML, Markdown or a print-ready PDF from the same source. See examples/ for a tour of every feature, and examples/templates/ for a sample per bundled template.

Quick start

Install from npm:

npm install -g @witlang/cli
wit tour path/to/file.wit
wit check path/to/file.wit
wit build path/to/file.wit -o out.html

Or, from a clone of this repo:

pnpm install
pnpm build
node packages/cli/dist/bin.js parse path/to/file.wit
node packages/cli/dist/bin.js check path/to/file.wit
node packages/cli/dist/bin.js build path/to/file.wit -o out.html

Subcommands: check, build, fmt, migrate (0.2 → 0.3), tour, parse, tokens; wit --help prints the usage. wit build doc.wit -o doc.pdf --template thesis builds with a bundled template.

VS Code extension

To install the editor extension locally from this repo (no marketplace required):

pnpm vscode:install

This builds the extension, packages it as a .vsix, installs it via the code CLI, and cleans up the artifact. Requires VS Code 1.94+ and the code command on your PATH (one-time setup: in VS Code, Cmd-Shift-P → Shell Command: Install 'code' command in PATH). After install, reload your VS Code window to activate.

For iterative extension development, F5 from packages/vscode/ opens a child VS Code window with the extension live-loaded.

Packages

Package	Purpose
@witlang/parser	Lexer + parser → typed AST.
@witlang/runtime	Resolver + expander runtime.
@witlang/render-html	HTML renderer.
@witlang/render-markdown	Markdown renderer.
@witlang/cli	wit command-line tool.
@witlang/skill	Claude Code authoring skill — npx @witlang/skill init drops a SKILL.md into a downstream project so agents write Wit idiomatically.

The VS Code extension lives in packages/vscode/ and is not on npm (install via pnpm vscode:install from a clone).

Architecture

The pipeline runs in five stages. Each stage owns one TypeScript package and a stable typed output:

   source.wit
       |
       v
  +---------+    +-----------+    +----------+    +---------+    +--------+
  |  lex    | -> |  parse    | -> | resolve  | -> | expand  | -> | render |
  | (chars) |    | (tokens   |    | (binding |    | (inline |    |  HTML  |
  |         |    |  -> AST)  |    |  + refs) |    |  + eval)|    |        |
  +---------+    +-----------+    +----------+    +---------+    +--------+
        @witlang/parser               @witlang/runtime            @witlang/render-html

• lex / parse — packages/parser turns the source string into an AST Document.
• resolve — packages/runtime walks the AST, binding every @name use to its #name definition (single-file or cross-file via reference ./other.wit).
• expand — same package, splices NodeDef bodies into use-sites, evaluates (if …), unrolls (each …), runs <% … %> scripts.
• render — packages/render-html walks the expanded AST and emits semantic HTML; packages/render-markdown does the same for Markdown.
• driver — packages/cli chains them behind one binary; the packages/vscode extension hosts an LSP that runs the same stages inside the editor.

Status

v0.3.0. A syntax redesign over 0.2 — parameters in glued parens, the ::body:: slot, the parenthesis form (h1 … h1), bundled templates, and prose that never turns into structure by accident. wit migrate rewrites 0.2 sources. See CHANGELOG.md and the language spec in docs/spec.md, whose every example is a test. Zero runtime dependencies.

Repository layout

• packages/parser — lexer + parser, AST types, error codes.
• packages/runtime — resolver, expander, lh script bridge.
• packages/render-html — reference HTML renderer.
• packages/render-markdown — reference Markdown renderer.
• packages/cli — wit command-line driver.
• packages/skill — Claude Code authoring skill + wit-skill init installer.
• packages/vscode — VS Code extension (LSP client + server, TextMate grammar).
• examples/ — one short .wit file per language feature (see the tour); examples/templates/ — one per bundled template.
• packages/runtime/templates/ — the bundled templates (reference wit/<name>).
• tests/ — fixtures (categorised), error sidecars, integration documents, shared test runner.
• PLAN.md, RULES.md — design log and engineering constraints.
• docs/spec.md — the language spec; every example in it is a test.

Contributing

See CONTRIBUTING.md. Issues and PRs welcome — I aim to triage within a week.

License

MIT.