Typsite Documentation

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]