inline inline 函数的 fit-font fit-font 参数语义发生了变更：

• 0.1.7 之前： fit-font fit-font 为 bool bool 类型
• 0.1.7 之后： fit-font fit-font 为 1em 1em 类型（可以是 true true 、 false false 或 1em 1em 、 2em 2em 等 em 值）

迁移方式：

• inline(content, fit-font: true) inline(content, fit-font: true) |-> inline(content, fit-font: 1em) inline(content, fit-font: 1em)
• inline(content, fit-font: false) inline(content, fit-font: false) |-> inline(content) inline(content) 或 inline(content, fit-font: false) inline(content, fit-font: false)

如果你在站点库中自定义了 inline inline 函数，需要更新调用方式：

// 旧版本
#import "@local/typsite:0.1.0": inline

// 新版本
#let footnotes = state("footnotes", ())
#let inline(..args) = context {
  import "@local/typsite:0.1.0": inline
  inline(..args, footnotes: footnotes.get())
}

// 旧版本
#import "@local/typsite:0.1.0": inline

// 新版本
#let footnotes = state("footnotes", ())
#let inline(..args) = context {
  import "@local/typsite:0.1.0": inline
  inline(..args, footnotes: footnotes.get())
}

rule.typ rule.typ 中的以下函数需要接收 footnotes footnotes 参数：

• rule-ref(footnotes) rule-ref(footnotes) 替代旧的 rule-ref rule-ref
• rule-footnote(footnotes) rule-footnote(footnotes) 替代旧的 rule-footnote rule-footnote

在 schema schema 函数中，需要先获取 footnotes 再传递给 rule：

let _footnotes = query(footnote).map(it => it.at("label", default: none)).filter(it => it != none)
show: rule-footnote(_footnotes)
show: rule-ref(_footnotes)

let _footnotes = query(footnote).map(it => it.at("label", default: none)).filter(it => it != none)
show: rule-footnote(_footnotes)
show: rule-ref(_footnotes)

@local/typsite:0.1.0 @local/typsite:0.1.0 中的 inline inline 函数现在需要接收 footnotes footnotes 参数：

// 旧版本
inline(content, fit-font: true, scale: 100%)

// 新版本
inline(content, fit-font: 1em, scale: 100%, footnotes: ())

// 旧版本
inline(content, fit-font: true, scale: 100%)

// 新版本
inline(content, fit-font: 1em, scale: 100%, footnotes: ())

auto-sized-svg auto-sized-svg 函数新增了 fit-font fit-font 参数，支持更多字体大小控制方式：

• true true ：使用 CSS font-size 继承
• false false ：使用固定 font-size: 1rem
• 1em 1em ：使用相对 em 值

如果你使用 Zed 作为编辑器，可以使用以下配置来获得更好的 Typst 开发体验：

在 .zed/settings.json .zed/settings.json 中添加：

{
  "lsp": {
    "tinymist": {
      "initialization_options": {
        "exportPdf": "never",
        "rootPath": "你的站点根目录/root",
      },
    },
  },
}

{
  "lsp": {
    "tinymist": {
      "initialization_options": {
        "exportPdf": "never",
        "rootPath": "你的站点根目录/root",
      },
    },
  },
}

如果你之前使用 VSCode 并配置了 tinymist，需要更新 rootPath rootPath 为绝对路径：

在 .vscode/settings.json .vscode/settings.json 中：

{
  "tinymist.rootPath": "/absolute/path/to/your/site/root"
}

{
  "tinymist.rootPath": "/absolute/path/to/your/site/root"
}

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 会等待正在执行的构建结束，再退出。

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