Typst 能力展示

Typst 不只是把文字转换成 HTML。下面七个可运行示例分别展示它的排版、编程、组件化、多格式输出与跨文章组织能力。

01 数学与引用 MathML、自动编号、交叉引用 02 内容即程序 函数、循环、数组生成数列 03 数据可视化 计算结果自动生成柱形图 04 可复用组件 四种 Markdown 风格 Callout 05 原生图形 布局原语生成矢量流程图 06 多格式同源 一份正文生成 HTML 与 PDF 07 跨文章与同步块 章节深链、共享内容单一来源

以下示例都由 Typst 在构建时实际计算和渲染，而不是预先准备的截图。

本页面和可下载的 PDF 调用同一个 showcase-body()；页面外壳分别负责 Web 导航和纸张版式。

数学公式与交叉引用

能力： 原生数学语法、MathML 输出、自动编号和稳定的交叉引用。

实时渲染结果： 设一组观测值为 $𝑥_{1}, \dots, 𝑥_{𝑛}$ ，它们的算术平均数是

𝑥 = \frac{1}{𝑛} \sum_{𝑖 = 1}^{𝑛} 𝑥_{𝑖} .

方差可以继续复用 (1) 中定义的 $𝑥$ ：

𝑠^{2} = \frac{1}{𝑛 - 1} \sum_{𝑖 = 1}^{𝑛} {(𝑥_{𝑖} - 𝑥)}^{2} .

公式编号和“(1)”“(2)”这样的引用关系由 Typst 计算，而不是手工填写。增删前面的公式后，编号会自动更新。

内容即程序

能力： 在文档中定义函数、执行循环，并对数组做 map 变换。

Typst 源码： 下面不是预先抄写好的数列。fibonacci 函数通过循环计算第 $𝑛$ 项，range 产生输入数组，map 对每个输入调用函数：

#let fibonacci(n) = {
  let a = 0
  let b = 1
  for _ in range(n) {
    let next = a + b
    a = b
    b = next
  }
  a
}
#let samples = range(9).map(n => (n, fibonacci(n)))

随后，Typst 将 samples 数组展开成表格：

$𝑛$	0	1	2	3	4	5	6	7	8
$𝐹_{𝑛}$	0	1	1	2	3	5	8	13	21

这里实际执行了函数、循环和数组变换。把 range(9) 改为 range(12)，Typst 会重新计算新增的三项并扩展表格；同样的机制也可以生成目录、术语表、实验矩阵或 API 文档。

数据驱动可视化

能力： 让图形直接消费前一节算出的 fibonacci-samples，避免表格和图表各维护一份数据。

图 1 由同一组斐波那契数据自动生成的柱形图

表格和图 1 共用 fibonacci-samples。修改输入范围或计算函数后，两种视图会在下一次构建中一起更新。

可复用 Callout

能力： 用一个函数约束重复出现的信息模块，同时保留不同的语义类型。

下面四个模块都调用同一个 callout(kind, title, body)，文章只提供类型、标题和正文；组件统一决定颜色、边框、间距以及深浅色适配。

NOTE

补充背景或解释，不打断正文的主线。

TIP

推荐做法：将反复出现的提示封装一次，在所有文章中复用。

WARNING

Typst 的 HTML 导出仍在发展，发布前应同时检查 HTML 与 PDF。

IMPORTANT

组件的视觉样式集中维护，正文只保存语义和内容。

原生图形

能力： 使用布局原语生成矢量图，而不是把外部截图粘贴进文章。

图 2 同一份结构化内容生成两种交付物

图 2 不是预先绘制的图片，而是由 Typst 的布局原语、文本和数学符号组成。PDF 直接保留矢量布局；HTML 后端通过 html.frame 将同一段布局嵌入为 SVG。

HTML 与 PDF 同源

能力： 内容只维护一次，再针对浏览器和纸张分别套用输出外壳。

这份演示刻意让两种输出承担不同职责：

HTML 提供响应式导航、深浅色主题和适合浏览器的阅读体验；
PDF 提供固定纸张、页码和适合归档或打印的版式；
标题、公式、表格、图形和解释文字只维护一次。

这就是本站采用 Typst 最直接的收益：不必在网页正文、数学插件和 PDF 工具链之间重复同步内容。

跨文章引用与同步块

能力： 使用稳定 URL 和 HTML 锚点跳到另一篇文章的具体章节；把公共内容定义在共享模块中，由多个页面共同导入。

下面的链接不是跳到文章顶部，而是直接定位到《你好，Typst 博客》的“发布流程”。URL 和锚点由 site-components.typ 统一维护。

SYNCED · 跨文章共享块

这段内容只定义在 content/_shared/site-components.typ 中，却会同时出现在第一篇文章的“发布流程”和展示页的“跨文章引用”中。修改一次共享函数并重新构建，两处内容会同步更新。

这里的“同步”发生在构建阶段：共享块只有一个事实源。它不是 Notion 那种浏览器中的实时嵌入，也不会复制另一篇文章的任意 DOM；每次构建时，Typst 会把共享函数展开到所有引用页面。