在 0.1.6 版本中，Typsite 进行了一系列重大更新，其中不可避免地包括一些breaking-changes ，遂纂写此文档以帮助用户更好地迁移到新版本。

1 Typsite Packages

将 Typst 库中与 typsite 紧密相关的部分单独抽离成一个Typst package，你可以在 typsite/packages 下找到与 typsite 的各个 packages。typsite 会将这些 packages 打包到二进制文件中，在每次 typsite compile typsite compile 时会自动将这些 packages 安装到 @local @local 目录下

当然，为了开发者调试包与使用包的方便，typsite 也提供了本地包自动安装，你只需要在 typsite compile typsite compile 时指明 --packages --packages 参数即可

如果在 watch-mode watch-mode 下，typsite 也会自动更新这些本地包并重新编译站点

所以，现在 typsite 的 Typst 库分为了两个部分：

@local/typsite:0.1.0 @local/typsite:0.1.0 ：包含了 typsite 的核心功能，提供各种基础函数，充当 typsite 与站点库之间的接口
- 通过这层接口，未来将很难有更多的 breaking-changes
root/lib/ root/lib/ : 每一个 typsite 站点的站点库，用户可以自定义其中的任何内容

2 迁移

如果您依赖了 0.1.6 之前的站点库，迁移到 0.1.6 版本时，您需要做如下替换：

import "lib.typ" import "lib.typ" |-> import "/lib/lib.typ" import "/lib/lib.typ"
html-text html-text |-> html.text html.text
text-align text-align |-> html.align html.align
- (注意不要把 /lib/site.typ /lib/site.typ 中的 text-align text-align 替换掉了)

推荐通过绝对路径去 import import lib.typ lib.typ ，如果您使用的是 tinymist 作为LSP, 您需要指定 Typst 的 root-path root-path 来获取更好的体验：

在 VSCode 中，您可以在站点目录的 .vscode/settings.json .vscode/settings.json 中添加如下配置：

"tinymist.rootPath": "站点目录的绝对路径/root"

"tinymist.rootPath": "站点目录的绝对路径/root"

对于我在此没有预期到的 breaking-changes ，您可以非常便捷地通过 typsite compile --port 8000 typsite compile --port 8000 开启 watch-mode watch-mode ，typsite会在您每次修改文件时给予您错误提示，您可以根据提示进行修复。

3 其他

支持了 Typst math -> mathml 的转换
- 这使得 typsite 可以更好地支持数学公式的展示，并且 mathml 转换会就地检测 Typst 的 math-font 并做兼容
inline inline 函数新增 fit-font fit-font 参数，可以自适应 Typst 的 context text.size context text.size
对于包含 Backlinks 与 References 的页面， <head> <head> 内的部分进行了去重优化，现在非常整洁
在默认的站点库中，对 show-rules show-rules 进行了模块化，你可以非常方便的在 /lib/lib.typ /lib/lib.typ 中添加/删除/修改 show-rule show-rule
在默认站点配置中，优化了连接的 title title , 你可以预览到 连接的标题 [链接地址] 连接的标题 [链接地址] 了

Backlinks

迁移到 Typsite 0.1.7 [migrate-to-017]

Glomzzz
2026-03-02 18:25

在 0.1.7 版本中，Typsite 进行了一系列关于SVG兼容的更新，其中不可避免地包括一些breaking-changes ，遂纂写此文档以帮助用户更好地迁移到新版本。

1 0.1.6 迁移

如果你从 0.1.6 之前的版本迁移，请确保也完成了 0.1.6 的迁移步骤：迁移到 Typsite 0.1.6

2 .typsite 配置迁移

在 0.1.7 版本中，.typsite 目录新增了以下组件和重写器：

.typsite/components/anchor_def_svg.html .typsite/components/anchor_def_svg.html ：SVG 锚点定义组件
.typsite/components/anchor_goto_svg.html .typsite/components/anchor_goto_svg.html ：SVG 锚点跳转组件
.typsite/rewrite/footnote-ref-svg.html .typsite/rewrite/footnote-ref-svg.html ：脚注引用的 SVG 重写器

如果你是从旧版本升级的，请确保将这些新文件复制到你的站点 .typsite 目录中。

3 /root/lib 库迁移

3.1 inline 函数签名变更

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)

3.2 库导入变更

如果你在站点库中自定义了 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())
}

3.3 rule 函数签名变更

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)

4 /packages 包迁移

4.1 inline 函数新增 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: ())

4.2 auto-sized-svg 新增 fit-font 参数

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

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

5 Zed 编辑器兼容

5.1 Zed LSP 配置

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

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

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

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

5.2 VSCode 设置迁移

如果你之前使用 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"
}

6 其他更新

新增 SVG 锚点支持，可以在 Typst 内容中创建可跳转的锚点
脚注引用现在支持 SVG 内联渲染
改进了 inline inline 函数的字体大小自适应机制
支持更灵活的 fit-font fit-font 参数，可以指定具体的 em 值