Typst 于 0.13 0.13 增加了 HTML 导出功能，包括 html-export 模式以及两个核心函数： html.elem html.elem 和 html.frame html.frame —— 我们可以利用这些函数来基于 Typst 编写以HTML+CSS为目标内容。

受此启发，我用 Rust 开发了名为 Typsite 的静态站点生成器.

目前，Typst 的 HTML 导出:

• 对简单富文本已有良好支持
• 复杂样式需要用户通过 html.elem html.elem 函数手动编写
• 无法自动将所有 Typst 生态内容转换为 HTML
• 对于包含复杂 Typst 样式的内容，可以使用 html.frame html.frame 将其转为 SVG 并嵌入 HTML
• 对于每一次 compile, 只支持单文件 HTML 输出

对于详细的已支持内容与计划可以追踪这个issue: HTML export #5512

虽然官方有计划支持自动 typst style -> HTML+CSS，但这并不会与 Typsite 产生任何冲突。 恰恰相反，Typst 的发展将使 Typsite 更加实用，因为 Typsite 主要职能是协调文章间的交互，并最终构建一套功能完善的静态网站。

在指定目录中初始化一个新的 typsite 项目

用法: typsite init [OPTIONS]

选项:
  -d, --dir <DIR>  项目根目录 [默认: ./]
  -h, --help       打印帮助

在指定目录中初始化一个新的 typsite 项目

用法: typsite init [OPTIONS]

选项:
  -d, --dir <DIR>  项目根目录 [默认: ./]
  -h, --help       打印帮助

编译或监听项目，指定输入和输出目录

用法: typsite compile [OPTIONS]

选项:
      --host <HOST>      服务主机 [默认: localhost]
      --port <PORT>      服务端口, 如果非0则进入watch-mode [默认: 0]
      --config <CONFIG>  项目配置路径 [默认: ./.typsite]
      --cache <CACHE>    缓存目录 [默认: ./.cache]
  -j, --jobs <JOBS>      并发导出的文章数 [默认: 可用 CPU/Rayon 预算]
  -i, --input <INPUT>    Typst 根目录，存放 typst 文件的位置 [默认: ./root] [别名: --i]
  -o, --output <OUTPUT>  输出目录 [默认: ./publish] [别名: --o]
  -p, --packages <PACKAGES>  本地包目录，typsite会将在此目录的包自动安装到@local，若在watch-mode则会自动同步，如果为空或未找到目录则跳过 [默认: ""] [别名: --p]
  -t, --typst <TYPST>    Typst 可执行程序路径 [默认: typst]
      --no-pretty-url
      --no-short-slug
  -h, --help             打印帮助

编译或监听项目，指定输入和输出目录

用法: typsite compile [OPTIONS]

选项:
      --host <HOST>      服务主机 [默认: localhost]
      --port <PORT>      服务端口, 如果非0则进入watch-mode [默认: 0]
      --config <CONFIG>  项目配置路径 [默认: ./.typsite]
      --cache <CACHE>    缓存目录 [默认: ./.cache]
  -j, --jobs <JOBS>      并发导出的文章数 [默认: 可用 CPU/Rayon 预算]
  -i, --input <INPUT>    Typst 根目录，存放 typst 文件的位置 [默认: ./root] [别名: --i]
  -o, --output <OUTPUT>  输出目录 [默认: ./publish] [别名: --o]
  -p, --packages <PACKAGES>  本地包目录，typsite会将在此目录的包自动安装到@local，若在watch-mode则会自动同步，如果为空或未找到目录则跳过 [默认: ""] [别名: --p]
  -t, --typst <TYPST>    Typst 可执行程序路径 [默认: typst]
      --no-pretty-url
      --no-short-slug
  -h, --help             打印帮助

清除缓存和输出目录

用法: typsite clean [OPTIONS]

选项:
      --input <INPUT>    受保护的 Typst 源文件目录 [默认: ./root]
      --config <CONFIG>  受保护的配置目录 [默认: ./.typsite]
      --force            检查路径后允许清理没有归属标记的旧目录
  -o, --output <OUTPUT>  输出目录 [默认: ./publish]
  -c, --cache <CACHE>    缓存目录，用于存储原始 Typst HTML [默认: ./.cache]
  -h, --help             打印帮助

清除缓存和输出目录

用法: typsite clean [OPTIONS]

选项:
      --input <INPUT>    受保护的 Typst 源文件目录 [默认: ./root]
      --config <CONFIG>  受保护的配置目录 [默认: ./.typsite]
      --force            检查路径后允许清理没有归属标记的旧目录
  -o, --output <OUTPUT>  输出目录 [默认: ./publish]
  -c, --cache <CACHE>    缓存目录，用于存储原始 Typst HTML [默认: ./.cache]
  -h, --help             打印帮助

查看代码高亮&语法支持列表
用法: typsite syntect [OPTIONS]

选项:
      --config <CONFIG>  项目配置路径 [默认: ./.typsite]
  -h, --help             打印帮助

查看代码高亮&语法支持列表
用法: typsite syntect [OPTIONS]

选项:
      --config <CONFIG>  项目配置路径 [默认: ./.typsite]
  -h, --help             打印帮助

Typsite 使用 Rayon 并行计算独立文件的指纹、校验导出缓存、解析文章 HTML 和渲染页面。Typst 导出使用独立的有界 Rayon 池：默认以可用 CPU 预算（同时参考 Rayon 池大小）为并发上限。每个 Typst 子进程再通过自身的 --jobs --jobs 分得一部分 CPU 预算，避免每个子进程都启动整台机器数量的工作线程。

typsite compile --jobs 4
# 内存受限或排查导出问题时，每次只运行一个文章子进程。
typsite compile --jobs 1

typsite compile --jobs 4
# 内存受限或排查导出问题时，每次只运行一个文章子进程。
typsite compile --jobs 1

-j -j 是 --jobs --jobs 的别名，参数必须是正整数。它控制的是同时导出的文章数，不是全部 Rayon 工作；文件指纹、解析和渲染的线程可另用 RAYON_NUM_THREADS RAYON_NUM_THREADS 调整。显式设置较大的 --jobs --jobs 可能增加内存使用，但实际并发数不会超过待导出的文章数。真正无变化的构建不会创建导出线程池。

包在导出前统一准备。各工作线程生成独立产物，全部结束后再按稳定的源文件顺序汇总。关系解析、依赖有序的元数据、缓存/归属检查点和过期删除仍保持有序。独立输出文件并行原子写入并同步数据，父目录按批次同步。已验证的无变化构建跳过配置解析，合法高亮资源按内容指纹缓存，共享依赖每批导出校验一次。只改变 --jobs --jobs 不会使缓存失效，也不会改变站点字节。

在 .typsite/options.toml .typsite/options.toml 中填写站点公开地址，即可生成 RSS 2.0 和站点地图：

[site]
base_url = "https://example.org"
title = "我的站点"
description = "笔记与文章"
rss_path = "/rss.xml"
sitemap_path = "/sitemap.xml"
rss_limit = 20
rss_content = "summary" # 可选 "summary" 或 "full"

[site]
base_url = "https://example.org"
title = "我的站点"
description = "笔记与文章"
rss_path = "/rss.xml"
sitemap_path = "/sitemap.xml"
rss_limit = 20
rss_content = "summary" # 可选 "summary" 或 "full"

请修改已有的 [site] [site] ，不要重复添加。把示例地址换成自己的公开地址后，运行 typsite compile typsite compile 。文件写入输出目录；每个生成页面的 HTML head 中都会加入 RSS 自动发现链接，读者可订阅 https://example.org/rss.xml https://example.org/rss.xml 。

文章元数据新增布尔选项 rss rss ，默认是 false false 。在集合页写上 #rss(true) #rss(true) ，并直接嵌入要订阅的文章：

#import "/lib/lib.typ": *
#show: schema.with("page")
#title[我的订阅集合]
#rss(true)

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

#import "/lib/lib.typ": *
#show: schema.with("page")
#title[我的订阅集合]
#rss(true)

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

只有直接嵌入的文章会成为订阅条目。标记为 rss: true rss: true 的集合页自身不进入 RSS，即使被其他集合页嵌入也不例外。标记不会被嵌入文章继承。嵌套嵌入不会自动成为独立条目，但全文模式仍会保留所选文章里的嵌入内容。引用、父级元数据和仅声明的 child 图关系不参与选择。多个集合页选出的文章合并去重，每篇只出现一次。

#rss(false) #rss(false) 将页面恢复为普通文章；如果仍被某个已标记的集合页直接嵌入，它仍可进入 RSS。没有标记集合页或没有可选直接嵌入时，已启用的订阅文件为空。日期排序和 rss_limit rss_limit 在选出条目之后应用。站点地图仍包含所有编译文章。

演示站点的两个首页都是集合页，各自直接嵌入文章指南和 Typst 简介，因此 RSS 共四个条目，而不是全部页面。旧站点库可从 @local/typsite:0.1.0 @local/typsite:0.1.0 导入 rss rss ，或合并新版 root/lib/lib.typ root/lib/lib.typ 的导入列表。

填写 base_url base_url 后，在初始化的演示站点目录运行：

typsite compile
typsite compile --port 8080

typsite compile
typsite compile --port 8080

检查 publish/rss.xml publish/rss.xml ，或在预览运行时打开 http://localhost:8080/rss.xml http://localhost:8080/rss.xml 。部署输出后，用公开地址（例如 https://example.org/rss.xml https://example.org/rss.xml ）订阅；预览地址只用于本地检查。

没有文件时，检查 base_url base_url 、 rss_path rss_path 、 rss_limit rss_limit ；文件为空时，检查是否存在带有可选直接嵌入的标记集合页。保留 [default_metadata.options].rss = false [default_metadata.options].rss = false ； #rss(true) #rss(true) 写在集合页，而不是准备发布的文章上。完整的升级操作见 0.1.8 RSS 迁移步骤 。

• summary summary 输出纯文本摘要，依次取非空的 description description 、 summary summary 、 abstract abstract 元数据。没有这些元数据时，不会自动截取正文。
• full full 还会在 content:encoded content:encoded 中包含组合后的文章 HTML，包括嵌入文章，但不包含页面模板、导航、侧边栏或引用与反向链接页脚。普通链接和图片地址会转为绝对 URL。脚本会被移除；RSS 阅读器可能无法像网页一样显示 SVG、MathML、交互元素或站点专用 CSS。
• 标题优先使用 page-title page-title ，其次为 title title 。排序时间依次取 updated updated 、 lastmod lastmod 、 date date ，由新到旧；时间相同时按 URL 排序。 pubDate pubDate 使用发表 date date ，缺失时回退到修改时间。
• 日期支持 YYYY-MM-DD YYYY-MM-DD 、 YYYY-MM-DD HH:MM[:SS] YYYY-MM-DD HH:MM[:SS] （按 UTC）、RFC 3339 和 RFC 2822。无效或未知日期会被省略，不会写出不合法的 RSS 日期。
• base_url base_url 留空会关闭两种输出。 rss_path rss_path 留空或 rss_limit = 0 rss_limit = 0 只关闭 RSS； sitemap_path sitemap_path 留空只关闭站点地图。关闭或改名后，旧生成文件通过归属记录清理。
• 修改订阅配置只重新组合输出，不会让未变更文章重新经过 Typst 导出。 --no-pretty-url --no-pretty-url 会反映在文章链接中。

文章可以使用现有辅助函数提供元数据：

#title[一篇文章]
#date[2026-03-02 18:25]
#metacontent("summary")[写给订阅阅读器的简短介绍。]
#metacontent("updated")[2026-03-03T09:00:00Z]

#title[一篇文章]
#date[2026-03-02 18:25]
#metacontent("summary")[写给订阅阅读器的简短介绍。]
#metacontent("updated")[2026-03-03T09:00:00Z]