Install & your first document

Wit runs on Node 20+. Install the command-line tool, then build a real document from an empty file — prose first, structure added one piece at a time.

Install the CLI

npm install -g @witlang/cli

Check it landed:

wit --version

That prints the installed version. The wit command has no runtime dependencies, so the install is quick. Below Node 20 the tool won't run — upgrade Node, not Wit.

Write some prose

Make a file called hike.wit and type ordinary sentences. A blank line starts a new paragraph; nothing else is required.

We reached Cairn Loop just after seven, ahead of the heat.

The ridge was quiet — a single hawk, and the wind doing all
the talking.

Build it to a web page:

wit build hike.wit -o hike.html

Open hike.html. Two clean paragraphs in a finished-looking theme — you wrote no CSS, because the default HTML output is a complete, self-contained styled page.

Add a heading and emphasis

Put a title on top and mark a few words. *stars* make bold, _underscores_ make italic:

(h1 Weekend hike: Cairn Loop h1)

We reached Cairn Loop *just after seven*, ahead of the heat.
The ridge was _completely_ silent.

Rebuild and refresh. The (h1 … h1) is a real heading, the starred words are bold, the underscored word italic. Everything you didn't mark stayed exactly as typed — 5*6*7 and file_name are never touched.

Add a list

A list runs over several lines, so it uses the block form: @ul opens it and ul@ closes it. Each item fits on a line, so it uses the parenthesis form.

source

(h2 What we packed h2)

@ul
(li Two litres of water each li)
(li Windshell and gloves li)
(li Trail bars li)
ul@

result

What we packed

Two litres of water each
Windshell and gloves
Trail bars

That renders a <ul> of three items. Indent the items if you like — indentation is for your eyes only. Swap @ul for @ol to number them.

Add a table

A captioned table, written in place:

source

@table(caption: Splits, rows: [
  [Segment, Distance, Time]
  [Trailhead to ridge, 4.2 km, 1h10]
  [Ridge to summit, 2.8 km, 55m]
])

result

Splits
Segment	Distance	Time
Trailhead to ridge	4.2 km	1h10
Ridge to summit	2.8 km	55m

Wit builds a full <table>: a <caption>, a <thead> from the first row, and a <tbody> from the rest. Each row is one line in square brackets; commas separate the cells.

Add a figure

A picture with a real caption (any .png beside the file works for src):

@figure
@img(src: ./ridge.png, alt: The ridge at dawn)
(figcaption First light on the ridge. figcaption)
figure@

You get a semantic <figure> wrapping the <img> and its <figcaption>. The src and alt go in parentheses because they describe the image; the caption is text the reader reads, so it is the body.

The whole file

(h1 Weekend hike: Cairn Loop h1)

We reached Cairn Loop *just after seven*, ahead of the heat.
The ridge was _completely_ silent.

(h2 What we packed h2)

@ul
(li Two litres of water each li)
(li Windshell and gloves li)
(li Trail bars li)
ul@

@table(caption: Splits, rows: [
  [Segment, Distance, Time]
  [Trailhead to ridge, 4.2 km, 1h10]
  [Ridge to summit, 2.8 km, 55m]
])

@figure
@img(src: ./ridge.png, alt: The ridge at dawn)
(figcaption First light on the ridge. figcaption)
figure@

The edit loop

Edit the file, run build, refresh the output. Two commands help alongside build:

wit check hike.wit — report parse and reference errors without building.
wit fmt hike.wit — tidy indentation without changing meaning (-w writes it back).

Build to PDF, Markdown, or a fragment

The -o extension picks the format:

-o hike.html — a complete, styled, self-contained page.
-o hike.md — clean Markdown, the same source for a different pipeline.
-o hike.pdf — a paginated, print-ready PDF.
No output flag — the HTML prints to your terminal, handy for piping.

Two flags fine-tune HTML: --fragment emits just the bare <article> for pasting into an existing site, and --raw swaps the built-in theme for a minimal reset so you can bring your own CSS.

PDF is the one format with a system requirement: Wit paginates its HTML through a headless Chrome, so a system Chrome or Chromium must be installed. If none is found, the build says so and names the fix:

wit build: no headless Chrome/Chromium found for PDF output.
Install Google Chrome, or point WIT_CHROME at a browser executable.