Rendering & styling

One .wit source builds to four outputs. The -o extension picks the format; two flags shape the HTML; three levels of styling take you from zero effort to full art direction.

Pick a format with -o

The extension on -o decides what you get:

wit build doc.wit -o doc.html    ~ complete self-contained styled page
wit build doc.wit -o doc.md      ~ GitHub-flavoured Markdown
wit build doc.wit -o doc.pdf     ~ paginated print-ready PDF

With no -o, the HTML prints to stdout — handy for piping:

wit build doc.wit | grep &#39;<h1>&#39;

"Self-contained" means the theme's CSS is inlined into the page head: one file you can open in any browser or email with no stylesheet shipped alongside. An unrecognised extension is an error, not a guess.

HTML variants: --fragment and --raw

To drop the content into a page you already have — a blog template, a CMS — ask for a fragment. You get just the bare <article>, no page head and no theme:

wit build doc.wit --fragment

To keep the full page shell but drop the built-in theme, use --raw. It leaves a minimal reset instead, so you bring your own CSS:

wit build doc.wit --raw -o doc.html

Styling, three levels

Level 1 — the default theme, no work.

Out of the box a built document looks like a clean word-processor page: a sans-serif body, a comfortable reading measure, an inch of margin on a soft grey canvas. It follows dark-mode preference and carries print rules so PDFs paginate sensibly — headings, figures, and tables kept from breaking across pages. You write no CSS.

Level 2 — small overrides with a style block.

To change one thing, drop a @@style … style@@ literal into the document. Its CSS cascades over the theme, touching only what you name. The theme scopes its rules to the document's own .wit-doc class, so scope your overrides there too:

source

@@style
.wit-doc { --wit-accent: #2b6a4f; }
style@@

result

Level 3 — full control with --raw.

Build with --rawfor a blank canvas, then style everything with your own style blocks and wrapping nodes. The same CSS drives HTML and PDF, so your print rules carry straight into the PDF.

Inside a raw @@@ node body you can inject a value with {{path}} interpolation — useful when a colour or size lives in your data:

@@style
.wit-doc { --wit-accent: {{theme.accent}}; }
style@@

Markdown, briefly

Markdown output is GitHub-flavoured: headings, bold and italic, lists, pipe tables, blockquotes. Right for a README, an issue, or any portable plain text. A few HTML-only features degrade — a hard line break becomes a space, and embedded audio or video has no Markdown equivalent.

PDF needs a browser

PDF paginates the HTML through a headless Chrome, so a system Chrome or Chromium must be installed (or point WIT_CHROME at a browser executable). Without one, the build stops and names the fix. HTML and Markdown need no browser.