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]
  -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             打印帮助

清除缓存和输出目录

用法: 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             打印帮助

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

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

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

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

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"
}