Migrating to Typsite 0.1.8

1. Back up your articles, root/lib root/lib , and .typsite .typsite , especially any custom templates or helpers.

2. Install Typsite 0.1.8 and the latest stable Typst. This release has been tested with Typst 0.15.1. Older Typst releases are not a compatibility target.

3. Generate a separate reference project; do not initialize over your existing site:

   typsite init --dir ../typsite-018-reference

   typsite init --dir ../typsite-018-reference

4. Compare that project’s root/lib root/lib and .typsite .typsite with yours. Merge the updated helpers without overwriting your customizations.

5. Run your usual compile command. Old internal caches are automatically treated as cache misses; a manual clean is not normally necessary.

   typsite --version
   typst --version
   typsite compile

   typsite --version
   typst --version
   typsite compile

6. Check both the rendered site and the command’s exit status before deploying. A failed build now exits with a nonzero status.

The cache now stores raw Typst HTML and fingerprints of the files Typst actually read. Imports and included files invalidate the appropriate exports. Parsed relationships and rendered fragments are not restored from old caches.

When publication is dirty, Typsite rebuilds the current relationship graph and recomposes all pages. Only changed output bytes are written. Removing a citation removes its old backlink; deleting or renaming an article removes its old owned output.

The output directory contains a separate ownership journal:

publish/.typsite-outputs.json

publish/.typsite-outputs.json

Keep this file. It is not a disposable cache. It lets Typsite remove stale generated files while preserving unrelated files. If it is corrupt, the build refuses to guess which files may be deleted. Back it up before repairing it; deleting it explicitly relinquishes ownership of previous outputs.

Outputs created before this journal existed are not automatically claimed or removed. If an old, deleted page remains after upgrading, remove that known obsolete file yourself, or explicitly clean the output directory after reviewing its contents.

# Review these directories first: clean removes their contents.
typsite clean --cache ./.cache --output ./publish --force

# Review these directories first: clean removes their contents.
typsite clean --cache ./.cache --output ./publish --force

typsite clean --input ./content --config ./config \
  --cache ./build-cache --output ./public --force

typsite clean --input ./content --config ./config \
  --cache ./build-cache --output ./public --force

Previously ignored errors can now stop a build. Fix or remove invalid resources rather than relying on them being skipped:

• Schemas, components, and rewrite HTML must have complete <head>...</head> <head>...</head> and <body>...</body> <body>...</body> envelopes. A deliberately empty <head/> <head/> or <body/> <body/> is allowed.
• Malformed themes, syntax definitions, syntax metadata, and rewrite resources are errors, even if unused. Duplicate resource identities are rejected.
• A page cannot explicitly name itself as its parent or embed itself. Cycles in parent inheritance, embeds, or metadata dependencies are rejected instead of hanging. Ordinary mutual citations and self-citations remain allowed.
• Source, configuration, cache, and output roots must not overlap; package sources must not overlap cache or output roots. Output collisions, case-only collisions, escaping paths, and symlinked managed output paths are rejected. Spaces and bracket characters in directory names are supported literally.
• .typsite.lock .typsite.lock and .typsite-outputs.json .typsite-outputs.json are reserved output names, including case variants and descendants beneath those names.

--packages --packages still names a directory of local package sources, not a Typst namespace. Invalid package names/versions and duplicate identities are rejected before installation.

For an isolated namespace, set TYPST_PACKAGE_PATH TYPST_PACKAGE_PATH ; packages will be installed beneath local/<name>/<version> local/<name>/<version> . Typsite also honors TYPST_PACKAGE_CACHE_PATH TYPST_PACKAGE_CACHE_PATH . For example, in a POSIX shell:

export TYPST_PACKAGE_PATH="$PWD/.typst-packages"
export TYPST_PACKAGE_CACHE_PATH="$PWD/.typst-package-cache"
typsite compile

export TYPST_PACKAGE_PATH="$PWD/.typst-packages"
export TYPST_PACKAGE_CACHE_PATH="$PWD/.typst-package-cache"
typsite compile

Keep these directories separate from the source, configuration, build cache, and output roots. Without an override, the default shared package installation behavior is retained. Use project fonts and a fixed SOURCE_DATE_EPOCH SOURCE_DATE_EPOCH when you need reproducible exports; changes to system fonts or undeclared external inputs may require discarding the build cache.

Independent file hashes, article parsing, and page rendering now use Rayon. Typst exports run concurrently with an automatic upper bound from the available CPU/Rayon budget (the earlier fixed four-article cap is removed). Each Typst subprocess receives a share of the CPU budget. Set typsite compile --jobs 1 typsite compile --jobs 1 to serialize article exports on low-memory machines, or --jobs 4 --jobs 4 to set an explicit limit ( -j -j is an alias; values must be positive).

--jobs --jobs does not control all Rayon work; use RAYON_NUM_THREADS RAYON_NUM_THREADS to tune hashing/parsing/rendering. Packages are prepared before workers start, results are collected in stable source order, and all workers finish before checkpoint/publication. Graph/metadata ordering, stale deletions, and publication ownership remain protected. Independent output files publish in parallel with atomic renames and data syncing. Disposable caches now use checksummed binary manifests with shared dependency sets, plus a content-keyed highlighting-resource cache; old formats rebuild automatically. Verified no-ops still hash-check actual inputs/artifacts/outputs but no longer reparse all configuration. Installed local packages are fingerprinted before export, avoiding unnecessary verification passes; newly discovered external inputs still need verification. Changing concurrency alone needs no cache clean and produces the same output bytes.

RSS 2.0 supports summaries or full article content. Setup has two separate parts: enable feed generation in the site configuration, then choose articles through a marked collection. The article metadata rss rss defaults to false; setting the site URL alone does not select any articles.

[site]
base_url = "https://example.org"
title = "My site"
description = "Notes and articles"
rss_path = "/rss.xml"
rss_limit = 20
rss_content = "summary" # "summary" or "full"
sitemap_path = "/sitemap.xml"

[site]
base_url = "https://example.org"
title = "My site"
description = "Notes and articles"
rss_path = "/rss.xml"
rss_limit = 20
rss_content = "summary" # "summary" or "full"
sitemap_path = "/sitemap.xml"

#import "/lib/lib.typ": *
#import "@local/typsite:0.1.0": rss
#show: schema.with("page")
#title[Feed collection]
#rss(true)

= #embed("./typst.typ")
= #embed("./article.typ")

#import "/lib/lib.typ": *
#import "@local/typsite:0.1.0": rss
#show: schema.with("page")
#title[Feed collection]
#rss(true)

= #embed("./typst.typ")
= #embed("./article.typ")

typsite compile
typsite compile --port 8080

typsite compile
typsite compile --port 8080

Preview still uses a nonzero --port --port . Every connected client observes the same build revision. A true no-op does not reload browsers. Export, parse, or render failures keep the last successfully published pages; successful repair triggers a reload. Ctrl-C waits for the in-flight build before shutting down.

Successful exports can be reused after a later publication failure. Fix the reported error and rerun the same command. Publication is atomic per file, not for the whole site: a failed publication may leave a mixture of complete old and new files, which a normal rerun repairs. Use a separate deployment step if you need an all-or-nothing site switch.