在 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 值

Backlinks

Typsite 文档 [index]

Glomzzz
2025-04-12 02:08

迁移到 Typsite 0.1.7

迁移到 Typsite 0.1.6

1 介绍

Typsite 是一个用于构建静态网站的工具，其文章内容由纯 Typst 编写，经由 Typsite 进行处理后，最终生成一个健全的静态站点。

2 功能

Typst 的常规表达
框架: 标题递增、小节模板、侧边栏、页脚
富文本：段落、小节、引用、代码块、数学公式、注脚、页面嵌入
将 Typst math 转换为 Mathml （自动检测math-font)
支持现代 Web 技术规范，如 HTML5、CSS3 和 JavaScript（ES6+）
增量编译, 实时预览

3 Typst 简介 [typst]

2025-04-27 18:39
Glomzzz

Typst 是一种现代化的排版系统，类似于 LaTeX，但设计更为简洁、易学，它主要用于创建学术论文、书籍、报告等需要精美排版的文档。

你可以在这里查看其官方英文文档：Typst Document
对于Typst的中文教程，我强烈推荐：Typst 蓝书 [天呐，这位编者非常清楚地知道自己是在阐述一套本体论!].

Typst

🔥已经崛起了!🔥

🚀这TeX人没收到通知吗？🚀

此节的剩余部分将会介绍 Typst & HTML -> Typsite

3.1 Typst 的 HTML 导出功能

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

3.2 Typsite：基于 Typst 的静态站点生成器

受此启发，我用 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 主要职能是协调文章间的交互，并最终构建一套功能完善的静态网站。

4 安装

通过 Release 页面下载二进制文件
- 请确保你已安装了0.13+的typst
通过 Nix & Flakes 构建
- 请确保你已经开启了 experimental-features = nix-command flakes experimental-features = nix-command flakes

git clone https://github.com/Glomzzz/typsite.git

cd typsite
nix build .

git clone https://github.com/Glomzzz/typsite.git

cd typsite
nix build .

5 初始化

通过 typsite init typsite init , 可以在当前文件夹初始化 Typsite.

.
├── root     ---  typst 根目录
│   ├── index.typ    --- 文章
│   └── lib.typ      --- typsite 库文件
├── .typsite --- typsite 配置目录
│   ├── assets       ---  资源目录 (会同步到输出目录)
│   ├── components   ---  组件模板
│   ├── themes       ---  代码高亮
│   ├── syntaxes     ---  代码语法
│   ├── rewrite      ---  重写器模板
│   ├── schemas      ---  页面模板
│   └── options.toml ---  项目配置
├── .cache   ---  缓存目录
└── publish  ---  输出目录

.
├── root     ---  typst 根目录
│   ├── index.typ    --- 文章
│   └── lib.typ      --- typsite 库文件
├── .typsite --- typsite 配置目录
│   ├── assets       ---  资源目录 (会同步到输出目录)
│   ├── components   ---  组件模板
│   ├── themes       ---  代码高亮
│   ├── syntaxes     ---  代码语法
│   ├── rewrite      ---  重写器模板
│   ├── schemas      ---  页面模板
│   └── options.toml ---  项目配置
├── .cache   ---  缓存目录
└── publish  ---  输出目录

6 写作

Typsite 兼容绝大部分 typst 的原生表达:

¹对于align, 请单独使用库中的 html.align html.align 函数

²对于复杂样式的元素, 请使用 inline inline 函数进行 svg 内联

7 命令行

用法: typsite <COMMAND>

命令:
  init     在指定目录中初始化一个新的 typsite 项目
  compile  编译或监听项目，指定输入和输出目录 [别名: c]
  clean    清除缓存和输出目录
  syntect  查看代码高亮&语法支持列表
  help     打印此消息或指定子命令的帮助信息

选项:
  -h, --help     打印帮助
  -V, --version  打印版本信息

用法: typsite <COMMAND>

命令:
  init     在指定目录中初始化一个新的 typsite 项目
  compile  编译或监听项目，指定输入和输出目录 [别名: c]
  clean    清除缓存和输出目录
  syntect  查看代码高亮&语法支持列表
  help     打印此消息或指定子命令的帮助信息

选项:
  -h, --help     打印帮助
  -V, --version  打印版本信息

7.1 init

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

用法: typsite init [OPTIONS]

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

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

用法: typsite init [OPTIONS]

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

7.2 compile

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

用法: typsite compile [OPTIONS]

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

7.3 clean

清除缓存和输出目录

用法: typsite clean [OPTIONS]

选项:
  -o, --output <OUTPUT>  输出目录 [默认: ./publish]
  -c, --cache <CACHE>    缓存目录，用于存储原始 typst_html_export 内容 [默认: ./.cache]
  -h, --help             打印帮助

清除缓存和输出目录

用法: typsite clean [OPTIONS]

选项:
  -o, --output <OUTPUT>  输出目录 [默认: ./publish]
  -c, --cache <CACHE>    缓存目录，用于存储原始 typst_html_export 内容 [默认: ./.cache]
  -h, --help             打印帮助

7.4 syntect

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

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

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

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

8 架构 & 流程

9 配置

你可以在这里看到所有的默认配置:

基于这些配置, 你可以完全地自定义你的整个站点.

schema: 页面模板, 负责处理页面框架
components / rewrites: 组件/重写器, 组成页面内容
assets: 资源文件目录, 会在compile时自动同步到输出目录
themes: 代码高亮文件
syntaxes: 代码语法文件

10 文章 [article]

2025-05-30 22:51
Glomzzz

TODO….

10.1 元数据

10.1.1 页面设置

10.1.2 元内容

10.1.3 文章关系

10.2 侧边栏

10.3 正文

10.3.1 标题

10.3.2 段落

10.3.3 路标

10.3.4 嵌入

10.3.5 注脚

10.3.6 链接

10.3.7 公式

10.3.8 内联

10.3.9 代码

10.3.9.1 Theme

10.3.9.2 Syntax

10.3.10 样式

10.3.10.1 对齐

10.3.10.2 高亮

10.3.10.3 彩字

10.3.10.4 加粗

10.3.10.5 斜体

10.4 页脚

10.4.1 Backlinks

10.4.2 References

要不先来看看内容示例