In version 0.13 0.13 , Typst added HTML export capabilities, including an html-export mode and two core functions: html.elem html.elem and html.frame html.frame — using these, we can write Typst documents targeting HTML+CSS output.

Inspired by this, I developed a static site generator in Rust called Typsite.

Currently, Typst’s HTML export:

• Has good support for basic rich text
• Requires users to manually write complex styles using the html.elem html.elem function
• Cannot automatically convert all Typst ecosystem content into HTML
• For content with complex Typst styles, html.frame html.frame can be used to convert them into SVG and embed them into HTML
• Only supports single-file HTML output per compilation

For details on supported features and the roadmap, follow this issue: HTML export #5512

Although the official team plans to support automatic typst style → HTML+CSS in the future, this won’t conflict with Typsite. On the contrary, Typst’s development will make Typsite even more useful, because Typsite’s main role is to coordinate interaction between articles and ultimately build a fully functional static website.

Initialize a new Typsite project in the specified directory

Usage: typsite init [OPTIONS]

Options:
  -d, --dir <DIR>  Project root directory [default: ./]
  -h, --help       Print help

Initialize a new Typsite project in the specified directory

Usage: typsite init [OPTIONS]

Options:
  -d, --dir <DIR>  Project root directory [default: ./]
  -h, --help       Print help

Compile or watch the project with specified input and output directories

Usage: typsite compile [OPTIONS]

Options:
      --host <HOST>          Serve host [default: localhost]
      --port <PORT>          Serve port, must be specified to watch mode [default: 0]
      --config <CONFIG>      Project config [default: ./.typsite]
      --cache <CACHE>        Cache dir [default: ./.cache]
  -j, --jobs <JOBS>          Concurrent article exports [default: automatic CPU/Rayon budget]
  -i, --input <INPUT>        Typst root dir, where your typst files are stored [default: ./root] [aliases: --i]
  -o, --output <OUTPUT>      Output dir [default: ./publish] [aliases: --o]
  -p, --packages <PACKAGES>  Packages dir, will be installed to @local and will be synced to @local in watch mode, skip if empty or not found [default: ] [aliases: --p]
  -t, --typst <TYPST>        Typst executable path [default: typst]
      --no-pretty-url
      --no-short-slug
  -h, --help                 Print help

Compile or watch the project with specified input and output directories

Usage: typsite compile [OPTIONS]

Options:
      --host <HOST>          Serve host [default: localhost]
      --port <PORT>          Serve port, must be specified to watch mode [default: 0]
      --config <CONFIG>      Project config [default: ./.typsite]
      --cache <CACHE>        Cache dir [default: ./.cache]
  -j, --jobs <JOBS>          Concurrent article exports [default: automatic CPU/Rayon budget]
  -i, --input <INPUT>        Typst root dir, where your typst files are stored [default: ./root] [aliases: --i]
  -o, --output <OUTPUT>      Output dir [default: ./publish] [aliases: --o]
  -p, --packages <PACKAGES>  Packages dir, will be installed to @local and will be synced to @local in watch mode, skip if empty or not found [default: ] [aliases: --p]
  -t, --typst <TYPST>        Typst executable path [default: typst]
      --no-pretty-url
      --no-short-slug
  -h, --help                 Print help

Clear cache and output directories

Usage: typsite clean [OPTIONS]

Options:
      --input <INPUT>    Protected Typst source directory [default: ./root]
      --config <CONFIG>  Protected configuration directory [default: ./.typsite]
      --force            Allow cleaning unmarked legacy directories after path checks
  -o, --output <OUTPUT>  Output directory [default: ./publish]
  -c, --cache <CACHE>    Cache directory for raw Typst HTML [default: ./.cache]
  -h, --help             Print help

Clear cache and output directories

Usage: typsite clean [OPTIONS]

Options:
      --input <INPUT>    Protected Typst source directory [default: ./root]
      --config <CONFIG>  Protected configuration directory [default: ./.typsite]
      --force            Allow cleaning unmarked legacy directories after path checks
  -o, --output <OUTPUT>  Output directory [default: ./publish]
  -c, --cache <CACHE>    Cache directory for raw Typst HTML [default: ./.cache]
  -h, --help             Print help

View the list of syntax highlighting and supported languages
Usage: typsite syntect [OPTIONS]

Options:
      --config <CONFIG>  Config path [default: ./.typsite]
  -h, --help             Print help

View the list of syntax highlighting and supported languages
Usage: typsite syntect [OPTIONS]

Options:
      --config <CONFIG>  Config path [default: ./.typsite]
  -h, --help             Print help

Typsite uses Rayon to hash independent files, check export caches, parse article HTML, and render pages in parallel. Typst exports run in a separate bounded Rayon pool: the automatic limit is the available CPU budget (also respecting the Rayon pool size). Each Typst subprocess receives a share of that CPU budget through its own --jobs --jobs option, rather than letting every subprocess spawn a full machine’s worth of workers.

typsite compile --jobs 4
# Low-memory or export debugging: one article subprocess at a time.
typsite compile --jobs 1

typsite compile --jobs 4
# Low-memory or export debugging: one article subprocess at a time.
typsite compile --jobs 1

-j -j is an alias for --jobs --jobs ; the value must be positive. This setting controls simultaneous article exports, not all Rayon work. Use RAYON_NUM_THREADS RAYON_NUM_THREADS to tune Rayon hashing/parsing/rendering separately. An explicit high --jobs --jobs limit can increase memory use; it is still bounded by the number of dirty articles. No export pool is created for true no-ops.

Packages are prepared before exports start. Workers produce independent artifacts, then the build joins them and records results in stable source order. Graph resolution, dependency-ordered metadata, cache/ownership checkpoints, and stale deletions stay ordered for correctness. Independent output files publish in parallel with atomic renames and data syncing; parent directories are synced once per batch. Verified no-ops skip configuration parsing, validated highlighting resources have a content-keyed cache, and shared dependencies are checked once per export batch. Changing --jobs --jobs alone does not invalidate the cache or change site bytes.

Set the public site URL in .typsite/options.toml .typsite/options.toml to generate RSS 2.0 and a sitemap:

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

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

Do not add a second [site] [site] section; edit the existing one. Replace the example URL with your actual public URL, then run typsite compile typsite compile . The files are written beneath the output directory. Every generated page receives an RSS autodiscovery link in its HTML head; readers can subscribe to https://example.org/rss.xml https://example.org/rss.xml .

Article metadata has a boolean rss rss option, defaulting to false false . Mark a collection page with #rss(true) #rss(true) , then directly embed the articles to publish:

#import "/lib/lib.typ": *
#show: schema.with("page")
#title[My feed collection]
#rss(true)

= #embed("./first-post.typ")
= #embed("./second-post.typ")

#import "/lib/lib.typ": *
#show: schema.with("page")
#title[My feed collection]
#rss(true)

= #embed("./first-post.typ")
= #embed("./second-post.typ")

Only those directly embedded articles become feed items. The marked collection page itself is excluded, even if another collection embeds it. The marker is not inherited by embedded articles. Nested embeds are not selected as separate entries; their content still appears inside a selected article in full mode. Citations, parent metadata, and graph-only child declarations do not select items. Multiple containers contribute a union of entries, with each article appearing only once.

#rss(false) #rss(false) makes a page an ordinary article again; it can still be included if a marked container embeds it. With no marked containers (or no eligible direct embeds), the enabled feed is empty. Date ordering and rss_limit rss_limit apply after selection. The sitemap still lists all compiled articles.

Both demo homepages are marked containers. They directly embed the article guide and Typst introduction in each language, so the demo feed has four entries, not every page. For older customized libraries, import rss rss from @local/typsite:0.1.0 @local/typsite:0.1.0 or merge the new root/lib/lib.typ root/lib/lib.typ import.

After setting base_url base_url , run these commands from the initialized demo directory:

typsite compile
typsite compile --port 8080

typsite compile
typsite compile --port 8080

Inspect publish/rss.xml publish/rss.xml , or open http://localhost:8080/rss.xml http://localhost:8080/rss.xml while preview is running. Deploy the output and subscribe using your public URL, such as https://example.org/rss.xml https://example.org/rss.xml ; the preview address is only for local checks.

No file? Check base_url base_url , rss_path rss_path , and rss_limit rss_limit . Empty feed? Check for a marked container with eligible direct embeds. Keep [default_metadata.options].rss = false [default_metadata.options].rss = false ; #rss(true) #rss(true) belongs on the collection, not on the posts you want to publish. A self-contained upgrade walkthrough is in the 0.1.8 RSS migration instructions .

• summary summary includes a plain-text description, taking the first nonempty description description , summary summary , or abstract abstract metadata value. It does not invent an excerpt when these are absent.
• full full additionally includes the composed article HTML in content:encoded content:encoded , including embedded articles but not the page schema, navigation, sidebar, or reference/backlink footer. Ordinary links and image URLs become absolute. Scripts are omitted; feed readers may not display SVG, MathML, interactive elements, or site-specific CSS exactly like the website.
• Titles use page-title page-title , then title title . Articles are ordered by updated updated , lastmod lastmod , then date date , newest first, with URLs breaking ties. pubDate pubDate uses the publication date date , falling back to the modification time.
• Dates accept YYYY-MM-DD YYYY-MM-DD , YYYY-MM-DD HH:MM[:SS] YYYY-MM-DD HH:MM[:SS] (UTC), RFC 3339, or RFC 2822. Invalid or unknown dates are omitted rather than emitting invalid RSS dates.
• An empty base_url base_url disables both outputs. An empty rss_path rss_path or rss_limit = 0 rss_limit = 0 disables RSS only. An empty sitemap_path sitemap_path disables only the sitemap. Disabled or renamed generated files are cleaned up through the ownership journal.
• Changing feed settings only recomposes outputs; unchanged articles are not re-exported with Typst. --no-pretty-url --no-pretty-url is reflected in article links.

Add metadata to an article with the existing helpers:

#title[An article]
#date[2026-03-02 18:25]
#metacontent("summary")[A short introduction for feed readers.]
#metacontent("updated")[2026-03-03T09:00:00Z]

#title[An article]
#date[2026-03-02 18:25]
#metacontent("summary")[A short introduction for feed readers.]
#metacontent("updated")[2026-03-03T09:00:00Z]

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.