Command reference

Useful when you want to do something beyond the basics, or when something doesn't behave as expected. unipress --help always describes the version you have installed.

Commands

unipress compile

unipress compile <dir> [options]
  --format <fmt>      Output format: pdf | typst | latex | docx | xlsx | epub | pagedjs.
                      Overrides the format: field in document.yml.
  --foundation <ref>  Override document.yml's foundation. Accepts:
                        - registry ref:  @<namespace>/<name>@<version>
                        - URL:           https://…/entry.js
                        - path:          ./foundation, /abs/path, …
  --out <path>        Output file (default: ./<dir>.<ext>).
  --variant <name>    Build an alternate top-level config <name>.yml inside <dir>
                      (--variant document-book reads document-book.yml) instead of
                      the default document.yml. The name is used as given.
  --config <path>     Explicit config file (default: <dir>/unipress.config.js).
  --typst-binary <p>  Path to a typst binary (skips the managed download).
  --keep-temp         On typst-compile failure, keep the temp dir for inspection.
  --yes               If no document.yml exists, generate one from the folder's
                      markdown without prompting (book foundation by default;
                      honors --foundation/--format).
  --verbose           Per-step progress to stderr + stack traces on errors.

Not every template makes every format. The book foundation behind article, book, monograph and report makes PDF, EPUB, Paged.js HTML and Typst source. The data foundation behind data-report and directory makes Excel and Word. Asking for another one stops with a message naming the formats available.

unipress create

unipress create <dir> [options]
  --template <id>     Template to scaffold (interactive picker if omitted).
                      Run `unipress list-templates` to see available ids.
  --title <str>       Document title (prompts if omitted).
  --author <str>      Document author (prompts if omitted).
  --force             Overwrite non-empty <dir>.
  --yes               Skip prompts (requires --template).

unipress list-templates

unipress list-templates
  List the templates available, with description, outputs,
  the foundation each pins, and the source URL where the foundation lives.

unipress inspect

unipress inspect <dir> [options]
  Dump the parsed content as JSON (debugging aid).
  --full              Include web-only fields (assets, icons, etc.).
  --summary           Replace pages[] with route strings only.
  --page <route>      Keep only the page matching <route>.
  --depth <n>         Truncate nested values beyond depth n.
  --foundation <ref>  Override document.yml's foundation.
  --no-orchestrate    Skip running the foundation; show only the parsed content.

Exit codes: 0 success, 1 user-addressable error, 2 internal error (re-run with --verbose for a stack trace).

document.yml

The content directory's config. The fields unipress reads:

site.yml is also accepted as a fallback, for compatibility with existing Uniweb site directories.

Several cuts of one manuscript

Keep more than one top-level config beside your content and pick one per build with --variant. The same chapters can ship as an A4 article and a trade book:

my-book/
  document.yml         # A4 article (the default: unipress compile .)
  document-book.yml    # trade 6×9 with covers
  assets/front.png
  01-intro.md  02-…

unipress compile .                          # the article (document.yml)
unipress compile . --variant document-book  # the book (document-book.yml)

Config-declared assets, such as book.covers.front, banners and logos, are resolved from the config the build reads. So covers must live in the config unipress reads (the --variant file or the default document.yml), not in a unipress.config.js --config override, whose asset paths aren't scanned.

unipress.config.js

An optional ESM file for things awkward in YAML: imports, computed values, format-specific overrides. It is found at <dir>/unipress.config.js, or named with --config <path>.

import { defineUnipressConfig } from '@uniweb/unipress'

export default defineUnipressConfig({
  out: './dist/my-book.pdf',           // overrides --out default
  format: 'pdf',                       // overrides document.yml format

  typst: {
    version: '0.14.2',                 // override the pinned Typst version
    binary: '/usr/local/bin/typst',    // skip the managed download
  },
})

A plain export default { … } works equally well; defineUnipressConfig is an identity wrapper for editor autocomplete. Relative paths in the config (out, foundation, typst.binary) resolve against the config file's directory.

Precedence

Applied per field:

CLI flags > unipress.config.js > document.yml > defaults

Typst binary

--format pdf needs a Typst binary. unipress pins a version and manages the download, verifying each one against a pinned SHA-256 digest.

• Cache location: $UNIPRESS_CACHE_DIR, else $XDG_CACHE_HOME/unipress, else ~/Library/Caches/unipress (macOS), else ~/.cache/unipress. The binary is at <cache>/typst/<version>/typst.
• Override: pass --typst-binary <path> or set typst.binary in unipress.config.js.

Custom foundations

Any foundation that declares an outputs: { … } map on its default export can drive unipress. Point document.yml's foundation: at:

• a registry ref: @<namespace>/<name>@<version>, fetched from unipress's foundation registry (https://uniweb.github.io/unipress, or the base UNIWEB_REGISTRY_URL names) and cached locally,
• a URL: https://…/entry.js,
• a local filesystem path: ./foundation, /abs/path, and so on.

The local-path form is the everyday dev loop. Point unipress at a foundation directory you're iterating on, with no publish step:

unipress compile my-doc --foundation ../my-foundation

For the foundation contract, see the foundation authors' guide and For developers. A foundation is not an npm package: unipress loads its built entry.js by URL, a registry ref being turned into one, or from a local path.

Where things stand

unipress is on 1.x. The CLI is stable enough to write real documents with, and the book template in particular is well tested. Future versions may change small things, and a change you may need to act on arrives as a minor version, but document.yml files and project folders from today should keep working: scaffolded projects pin a specific foundation version, and registry artifacts are immutable.