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]

Merge the updated root/lib/site.typ root/lib/site.typ from the reference project. The inline-math inline-math helper now runs in a contextual evaluation, queries footnote labels, and passes them through to the SVG renderer. Both inline and block fallback are supported:

#inline-math($a/b$)
#inline-math($sum_(i=1)^n i$, block: true)

#inline-math($a/b$)
#inline-math($sum_(i=1)^n i$, block: true)

Your existing call sites do not need a new signature. Typsite passes the HTML feature flag and html-frames html-frames input to Typst automatically.

The Typsite executable is version 0.1.8. The bundled Typst package keeps its existing identity:

#import "@local/typsite:0.1.0": *

#import "@local/typsite:0.1.0": *

Do not change this import to @local/typsite:0.1.8 @local/typsite:0.1.8 . The executable installs its bundled package before an export that needs it.

The initialized demo includes these migration pages, its templates, fonts, and SVG examples. It does not require preview-package downloads. From the reference project directory:

typsite compile
typsite compile --port 8080

typsite compile
typsite compile --port 8080

The second command starts preview mode. Open http://localhost:8080/ http://localhost:8080/ or /en/ /en/ . External music players and web-font links in the content examples still need a browser network connection; they are not build dependencies.

typsite clean typsite clean validates both roots before deleting anything, takes the build locks, and refuses source/configuration overlap. Nonempty legacy directories without ownership markers require an explicit opt-in:

# 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

If your source or configuration roots are nondefault, pass them too so they are protected:

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

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

--force --force permits unmarked legacy directories; it does not bypass path-safety checks or active build locks. Lock files may remain after cleaning. Do not delete .typsite.lock .typsite.lock while a build or preview process is running.

Edit the existing [site] [site] section in .typsite/options.toml .typsite/options.toml ; do not append a duplicate section. Replace the example URL with the public address where your site will be deployed:

[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"

Keep rss = false rss = false under [default_metadata.options] [default_metadata.options] (or omit it). This is the per-article default, not a switch under [site] [site] . Opt in on individual collection pages instead of setting every article to true.

Merge the new rss rss import in root/lib/lib.typ root/lib/lib.typ , or import it directly from the bundled package as below. For example, create root/feed.typ root/feed.typ using two existing demo articles:

#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")

This selects typst.typ typst.typ and article.typ article.typ , not feed.typ feed.typ . In your own site, replace these paths with your articles. Only direct embeds are selected; nested embeds, citations, parent links, and graph-only child declarations do not add entries. Multiple containers contribute a deduplicated union. Marked containers are always excluded, even when embedded by another container; their marker is not inherited by their children. #rss(false) #rss(false) removes a container marker, not an item selected by another container.

typsite compile
typsite compile --port 8080

typsite compile
typsite compile --port 8080

The first command writes publish/rss.xml publish/rss.xml (or your configured output/path). The second serves it at http://localhost:8080/rss.xml http://localhost:8080/rss.xml for inspection. Readers should subscribe to your deployed public URL, such as https://example.org/rss.xml https://example.org/rss.xml , not the localhost preview address. Each generated HTML page includes an RSS autodiscovery link.

The demo’s two homepages already use #rss(true) #rss(true) . With base_url base_url set, their direct embeds produce four entries: the article guide and Typst introduction in both languages. The additional feed.typ feed.typ above selects existing entries again, without duplicating them. Homepages, migrations, and example pages are not automatically included. The sitemap still includes all compiled articles.

• rss_content = "summary" rss_content = "summary" is the default: use the first nonempty description description , summary summary , or abstract abstract metadata. Add #metacontent("summary")[A short introduction.] #metacontent("summary")[A short introduction.] in the selected article; missing summaries do not exclude it.
• rss_content = "full" rss_content = "full" additionally includes composed article HTML without page navigation, sidebars, or reference/backlink footers. Embedded content remains within its selected article. Feed-reader support for SVG, MathML, and site-specific CSS varies.
• No rss.xml rss.xml : check that base_url base_url is nonempty, rss_path rss_path is nonempty, and rss_limit rss_limit is greater than zero. The default path and limit remain /rss.xml /rss.xml and 20. An invalid nonempty site URL fails validation.
• An empty feed: check #rss(true) #rss(true) and actual direct #embed(...) #embed(...) calls. Setting only [site].base_url [site].base_url is not enough, and rss = false rss = false is not an item opt-out.
• RSS dates use RFC 2822, not ISO timestamps. Date-only and YYYY-MM-DD HH:MM[:SS] YYYY-MM-DD HH:MM[:SS] metadata use UTC; RFC 3339/RFC 2822 offsets are normalized to UTC. Invalid dates are omitted, and titles/summaries are extracted as text rather than exposing HTML tags.

More settings and article metadata examples are in the homepage’s RSS section .