Compile, watch, serve

Compile

Use calepin compile when you want to execute code chunks and render a document. The command line shape is intentionally the same as typst compile: same output-first/format-driven arguments, with -- pass-through for Typst flags, plus Calepin preprocessing.

calepin compile paper.typ --format pdf
calepin compile paper.typ --format html
calepin compile paper.typ {p}.svg --format svg

# explicit output path
calepin compile paper.typ path/to/paper.pdf --format pdf

Compile a website by pointing calepin compile at a source directory that contains calepin.toml:

calepin compile docs docs
calepin compile my_site public

Arguments after -- are forwarded to Typst, so project-specific Typst flags can stay in the same command.

# open PDF in system viewer
calepin compile paper.typ -- --open

# set path to font directory
calepin compile paper.typ -- --font-path fonts

Watch

Use calepin watch while editing. It watches your source for changes, re-runs preprocessing, and delegates recompilation and previewing to typst watch. The command form is the same as typst watch: same positional arguments and pass-through flags, with Calepin running its preprocessing step first.

calepin watch paper.typ
calepin watch paper.typ --format html
calepin watch paper.typ {p}.svg --format svg

The default output format is PDF. Choose another format with --format, or let the output extension select the format.

Arguments after -- are passed through to typst watch. Typst’s --open flag opens the rendered output in the operating system’s default viewer, and Typst’s --port flag chooses the HTML preview port.

calepin watch example.typ -- --open
calepin watch paper.typ paper.html --format html -- --port 3001 --open

Watch a website directory by passing the source and output directories:

calepin watch docs docs
calepin watch my_site public

Add --serve to run the local server while watching a website. It uses the same --host, --port, and --open options as calepin serve.

calepin watch docs docs --serve --open
calepin watch my_site public --serve --host 127.0.0.1 --port 8001

PDF viewer auto-refresh

Some PDF viewers do not automatically refresh a document when it is regenerated on disk. For example, macOS Preview may keep showing an older PDF until the window is focused, the file is reopened, or the application is restarted.

For smoother live preview, use a PDF viewer that reloads the file when it changes. On macOS, Skim is a good option. Other platforms have similar auto-reloading viewers, which are useful when working with tools that repeatedly rebuild PDFs.

Serve

Use calepin serve to preview a compiled website directory locally. This is useful for checking routing, assets, Pagefind search, and links after a static build.

calepin serve docs
calepin serve public

By default, Calepin uses 127.0.0.1 and the first available port from

Set the host and port explicitly when you need a stable preview

URL:

calepin serve docs --host 127.0.0.1 --port 8001

Open the served website in your default browser:

calepin serve docs --open