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]

1. 备份文章、 root/lib root/lib 和 .typsite .typsite ，尤其是自己修改过的模板和辅助函数。

2. 安装 Typsite 0.1.8 和 Typst 最新稳定版。本次已测试 Typst 0.15.1，不保证兼容旧版 Typst。

3. 在另一个目录生成参考项目，不要在现有站点上直接初始化：

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

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

4. 对照参考项目的 root/lib root/lib 和 .typsite .typsite 合并更新，保留自己的定制。

5. 执行平常使用的编译命令。旧内部缓存会自动按缓存未命中处理，通常不需要先手动清理。

   typsite --version
   typst --version
   typsite compile

   typsite --version
   typst --version
   typsite compile

6. 部署前同时检查生成的页面和命令退出状态。构建失败现在会返回非零退出码。

新缓存保存 Typst 原始 HTML，以及 Typst 实际读取文件的指纹。导入或引用的文件变化时，会重新导出相应文章。旧缓存中的关系图和渲染片段不再恢复。

需要更新输出时，Typsite 会重新建立当前关系图，并重新组合所有页面，但只写入字节发生变化的文件。删除引用后，对应的旧反向链接会消失；删除或重命名文章后，旧的受管理输出也会移除。

输出目录中新增独立的归属记录：

publish/.typsite-outputs.json

publish/.typsite-outputs.json

请保留这个文件。 它不是可随意丢弃的缓存。Typsite 据此删除过期生成文件，同时保留无关文件。如果记录损坏，构建会拒绝猜测哪些文件可以删除；修复前请先备份。手动删除它，意味着放弃对之前输出文件的归属记录。

升级前生成、尚未被记录的文件不会被自动接管或删除。如果已经删除的旧页面仍留在输出目录中，请手动移除已确认过期的文件，或检查输出目录内容后显式执行清理。

# 先检查这两个目录；clean 会清空它们的内容。
typsite clean --cache ./.cache --output ./publish --force

# 先检查这两个目录；clean 会清空它们的内容。
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

过去被忽略的错误，现在可能导致构建失败。请修复或移除无效资源，不要再依赖静默跳过：

• 页面模板、组件和重写器 HTML 必须包含完整的 <head>...</head> <head>...</head> 与 <body>...</body> <body>...</body> 。有意留空时，可使用 <head/> <head/> 或 <body/> <body/> 。
• 损坏的主题、语法定义、语法元数据和重写器，即使没有用到，也会报错；重复的资源标识会被拒绝。
• 页面不能显式把自己设为父页面，也不能嵌入自己。父级继承、嵌入或元数据依赖形成循环时会报错，不再挂起；普通的相互引用和自引用仍然合法。
• 源文件、配置、缓存和输出目录不能相互重叠；本地包源也不能与缓存或输出目录重叠。输出冲突、仅大小写不同的路径冲突、越界路径和受管理输出中的符号链接会被拒绝。目录名中的空格和方括号按字面处理。
• .typsite.lock .typsite.lock 与 .typsite-outputs.json .typsite-outputs.json 是保留的输出名称，包括大小写变体，以及这些名称之下的路径。

--packages --packages 仍指向本地包的源文件目录，不是 Typst 包命名空间。安装前会拒绝无效的包名、版本和重复标识。

需要隔离时，可设置 TYPST_PACKAGE_PATH TYPST_PACKAGE_PATH ，包会安装到它下面的 local/<name>/<version> local/<name>/<version> 。Typsite 同时支持 TYPST_PACKAGE_CACHE_PATH TYPST_PACKAGE_CACHE_PATH 。例如在 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

这些目录应与源文件、配置、构建缓存和输出目录分开。没有指定路径时，仍保留默认的共享包安装行为。需要可复现导出时，请使用项目字体和固定的 SOURCE_DATE_EPOCH SOURCE_DATE_EPOCH ；系统字体或未声明的外部输入发生变化后，可能需要丢弃构建缓存。

独立文件指纹、文章解析和页面渲染现在使用 Rayon。Typst 并发导出默认以可用 CPU/Rayon 预算为上限（不再固定限制为四篇），每个子进程再分得部分 CPU 工作线程。内存受限时，可用 typsite compile --jobs 1 typsite compile --jobs 1 串行导出文章；也可用 --jobs 4 --jobs 4 明确限制并发数（别名 -j -j ，参数必须是正整数）。

--jobs --jobs 不控制全部 Rayon 工作；文件指纹、解析与渲染可通过 RAYON_NUM_THREADS RAYON_NUM_THREADS 调整。包在工作线程启动前统一准备，结果按稳定的源文件顺序汇总，全部线程结束后才记录检查点或发布。关系与元数据顺序、过期删除和发布归属仍受保护。独立输出并行原子替换并同步数据。可丢弃的缓存现在使用带校验和、共享依赖集的二进制清单和按内容指纹索引的高亮资源缓存，旧格式会自动重建。已验证的无变化构建仍检查输入、导出产物和输出的内容哈希，但不再重解析所有配置。已安装本地包在导出前计算指纹，避免不必要的验证导出；新发现的外部输入仍需验证。只改变并发数无需清缓存，生成的输出字节相同。

RSS 2.0 支持摘要或全文。配置分为两个步骤：先在站点配置中开启文件生成，再通过集合页选择文章。文章元数据 rss rss 默认是 false；只填写站点地址不会自动选出任何条目。

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

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

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

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

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

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

typsite compile
typsite compile --port 8080

typsite compile
typsite compile --port 8080

仍通过非零的 --port --port 启动预览。所有已连接客户端会观察到同一构建版本；真正没有变化的轮询不会刷新浏览器。导出、解析或渲染失败时保留上次成功发布的页面，修复成功后触发刷新。按 Ctrl-C 会等待正在执行的构建结束，再退出。

即使后续发布失败，已经成功导出的结果也能复用。修复报错后，重新运行相同命令即可。发布只保证单个文件的原子替换，不是整个站点的事务：发布中途失败可能留下完整的新旧文件混合状态，普通重试会修复。如果部署要求站点整体切换，请另设部署步骤。