Rendering & styling

One .wit source builds to HTML, Markdown, or PDF. 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

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 '<h1>'

"Self-contained" means the theme's CSS is inlined into the page head: one file you can open in any browser or email with nothing 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 but drop the built-in theme, use --raw. It leaves a minimal reset, so you bring your own CSS:

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

Styling, three levels

Level 1 — the default theme. A built document looks like a clean word-processor page: a sans-serif body, a comfortable reading measure, a soft grey canvas. It follows dark-mode preference and carries print rules so headings, figures, and tables don't break across PDF pages. You write no CSS.

Level 2 — small overrides with a style block. To change one thing, add a @@style … style@@ block. Its body is CSS, kept exactly as typed, and it cascades over the theme. The theme scopes its rules to the document's .wit-doc class, so scope your overrides there too:

source

@@style
.wit-doc { --wit-accent: #2b6a4f; }
.wit-doc .callout-card { border-left: 3px solid var(--wit-accent); }
style@@

result

Hang your own classes on nodes with a parameter — @div(class: callout-card) — and target them from the style block.

Level 3 — full control with --raw. Build with --raw for a blank canvas, then style everything yourself. The same CSS drives HTML and PDF, so your print rules carry straight into the PDF.

Data in a style block

Inside a @@ block, {{path}} inserts a value — useful when a colour or size lives in your data:

source

#brand: { accent: #2b6a4f } !!

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

result

That emits <style>.wit-doc { --wit-accent: #2b6a4f; }</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. HTML-only features degrade: a hard line break becomes a space, a figure becomes an image with its caption as alt text, and audio or video has no 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.