Typst 使用经验记录 - 璜珀的小屋

更新日志

2025-07-20
- 更新了在博客中使用 Typst 的相关建议，以及转换为 Markdown 的相关建议
- 添加了 Typst 符号手写识别的网页版本链接
- 修正了部分用词
2025-03-20
- 更新「目录不同层级标题使用不同样式」到 Typst 0.13 版本
- 在「结合 showybox 与 ctheorems 包制作美观定理环境」添加了提示
2025-02-28
- 更新「在 Typst 中绘制 LaTeX 符号」
2024-10-20
- 更新文章中部分链接
2024-10-08
- 更新「在文本中使用美观的大括号分类」
2024-10-02
- 更新「结合 showybox 与 ctheorems 包制作美观定理环境」
2024-10-01
- 更新「目录不同层级标题使用不同样式」
2024-09-27
- 发布文章。

warning

本文主要编写于 Typst 0.12.0 版本，部分内容未考虑新版本更新内容，可能已经过时。

如未特别注明，本文中的代码均基于 Typst 0.12.0 版本。

怎么找解决方案#

多翻翻别人趟过的坑：

翻文档
- Typst 中文文档（注：该文档长期未更新，已过时。建议参考官方英文文档。）
- Typst Documentation
翻示例

排版经验#

不同层级标题使用不同序号格式#

其实是如何为每一级标题指定不同的编号格式？ - 常见问题 | Typst 中文社区导航的重复造轮子，但是造轮子的时候没看到这个东西，造都造了就发出来算了。（用 Typst 非官方中文群群友的说法，在 numbly 包出来之前，人人都有自己的 numbly 轮子（笑））

1
#let diff_numbering(..schemes) = {
2
  (..nums) => {
3
    let nums_arr = nums.pos()
4
    let schemes_arr = schemes.pos()
5
    if nums_arr.len() >= schemes_arr.len() {
6
      numbering(schemes_arr.at(-1), ..nums)
7
    } else {
8
      numbering(schemes_arr.at(nums_arr.len() - 1), ..nums)
9
    }
10
  }
11
}
12
// 使用
13
#set heading(numbering: diff_numbering("第一章", "1.1", "1-1-1"))
14
= 一个章节
15
== 一个小节
16
=== 一个小节的小节
17
= 第二个章节
18
== 第二个章节的小节
19
=== 第二个章节的小节的小节

效果：

使用 numbly 包可以达到更好的效果：

1
#import "@preview/numbly:0.1.0": numbly
2
#set heading(numbering: numbly("一|{1:一}章", "a{1:1}.{2:1}", "1?{1:1}-{2:1}.{3:1}"))
3
= #lorem(1)
4
== #lorem(2)
5
=== #lorem(3)
6
== #lorem(2)
7
=== #lorem(3)
8
=== #lorem(3)
9
= #lorem(1)
10
== #lorem(2)
11
=== #lorem(3)

效果：

填空栏#

1
#let grid_blanks(cell: grid.cell, blank-width: 2em, line-width: 0.05em, colon: [: ], ..args) = grid(
2
  ..args.named(),
3
  ..args.pos().map(label => (cell([#label#colon#box(width: blank-width, stroke: (bottom: line-width))])))
4
)
5

6
// 使用
7
#grid_blanks(
8
  columns: (auto, auto),
9
  align: right,
10
  row-gutter: 1.5em,
11
  column-gutter: 1em,
12
  blank-width: 3cm,
13
  "姓名",
14
  "班级",
15
  "学号",
16
  "学校",
17
)
18

19
#grid_blanks(
20
  columns: (auto, auto),
21
  align: right,
22
  row-gutter: 1.5em,
23
  column-gutter: 1em,
24
  blank-width: 3cm,
25
  colon: [ $==>  integral_0^1 pi - 1$ ],
26
  "Name",
27
  "Class",
28
  "Id",
29
  "Grade",
30
)

效果：

页眉使用当前页面标题#

使用 hydra 包。需要其他设置可以参考 hydra 包的文档

1
#import "@preview/hydra:0.5.1": hydra
2

3
#set page(
4
  header: context align(
5
    {
6
      if calc.odd(here().page()) {
7
        right
8
      } else {
9
        left
10
      }
11
    },
12
    emph(hydra(1, skip-starting: false)),
13
  ),
14
)

效果：

note

效果演示使用的是我的多复变函数论笔记的 Typst 版本。

目录不同层级标题使用不同样式#

简易版#

1
#show outline.entry: it => {
2
  if it.level == 1 {
3
    strong(it)
4
  } else if it.level >= 3 {
5
    emph(it)
6
  } else {
7
    it
8
  }
9
}

效果如下：可以发现，页码也变得歪七倒八的。如果不介意，那么用这个简易版即可；反之，可以看下面的复杂版

复杂版#

0.12 版本

warning

Typst 0.13 大幅修改了 outline.entry 的接口，以下只适用于 Typst 0.12

1
#show outline.entry: it => {
2
  let loc = it.element.location()
3
  link(
4
    loc,
5
    if it.level == 1 {
6
      strong(it.body)
7
    } else if it.level >= 3 {
8
      emph(it.body)
9
    } else {
10
      it.body
11
    },
12
  )
13
  sym.space
14
  box(width: 1fr, it.fill)
15
  sym.space
16
  link(loc, it.page)
17
}

复杂版是直接照着 Typst 的 outline 函数源码来写的，只有标题的文字部分会修改样式，效果如下：

1
#show outline.entry: it => {
2
  // 获取 entry 原本的内容
3
  let prefix = outline.entry.prefix(it)
4
  let body = outline.entry.body(it)
5
  let page-number = outline.entry.page(it)
6

7
  // 修改 body
8
  body = if it.level == 1 {
9
    strong(body)
10
  } else if it.level >= 3 {
11
    emph(body)
12
  } else {
13
    body
14
  }
15

16
  // 重新组装 inner
17
  // 保持和 `outline.entry.inner(it)` 获取的结构一致
18
  let inner = {
19
    body
20
    sym.space
21
    box(width: 1fr, it.fill)
22
    sym.space
23
    page-number
24
  }
25
  let indented = outline.entry.indented(it, prefix, inner)
26
  link(it.element.location(), indented)
27
}

结合 showybox 与 ctheorems 包制作美观定理环境#

tip

目前有开箱即用的包 theorion，推荐使用这个。

本节内容参考了 showybox and ctheorems? · Issue #15 · sahasatvik/typst-theorems 的内容并进行了部分修改。

1
// --------- 定义函数 ---------
2
#import "@preview/ctheorems:1.1.2": *
3
#import "@preview/showybox:2.0.1": showybox
4

5
#let showy-thm(
6
  identifier,
7
  head,
8
  color: blue,
9
  ..showy-args,
10
  supplement: auto,
11
  base: "heading",
12
  base_level: none,
13
) = {
14
  let showy-fmt(name, number, body, ..args) = {
15
    showybox(
16
      title: {
17
        head
18
        number
19
        if name != none {
20
          [（#name）]
21
        }
22
      },
23
      frame: (
24
        border-color: color,
25
        title-color: color.lighten(30%),
26
        body-color: color.lighten(95%),
27
        footer-color: color.lighten(80%),
28
        radius: (top-left: 7pt, bottom-right: 7pt, rest: 2pt),
29
      ),
30
      ..args.named(),
31
      body,
32
    )
33
  }
34
  if supplement == auto {
35
    supplement = head
36
  }
37
  thmenv(
38
    identifier,
39
    "heading",
40
    none,
41
    (name, number, body) => showy-fmt(name, number, body, ..showy-args),
42
  ).with(supplement: supplement)
43
}
44

45
#let theorem = showy-thm(
46
  "theorem",
47
  "定理",
48
  title-style: (
49
    weight: "bold",
50
    boxed-style: (
51
      anchor: (x: left, y: horizon),
52
      offset: (x: 0pt, t: 0pt),
53
      radius: (top-left: 7pt, bottom-right: 7pt, rest: 2pt),
54
    ),
55
  ),
56
).with(numbering: "1.1")
57
#let lemma = showy-thm("lemma", "引理", color: green.darken(25%)).with(numbering: "1.1")
58
#let proof = thmproof("proof", "证明", inset: (x: 0em, top: 0em))
59
// --------- 定义函数 ---------
60

61
// --------- 使用演示 ---------
62
#show: thmrules
63
#theorem[
64
  对任何子集 $Omega subset CC^n$，$cal(O)(Omega)$ 在逐点加法和数乘意义下封闭。
65
  任一关于 $z_1, dots.c, z_n$ 的复系数多项式在 $CC^n$ 上是全纯的，从而在 $cal(O)(Omega)$ 里。
66
  若 $f, g in cal(O)(Omega)$，且 $g(z) eq.not 0, forall z in Omega$，则 $f slash g in cal(O)(Omega)$。
67
]
68
#theorem("F. Hartogs, 1906", numbering: none)[
69
  设 $D subset CC^n$ 为一区域，$f: D -> CC$。若 $f$ 分别关于每一单复变量 $z_j (1 <= j <= n)$
70
  全纯，则 $f in cal(O)(D)$。
71
]
72
#lemma("Osgood", numbering: none)[
73
  设 $D subset CC$ 为一区域，$f: D -> CC$。若 $f in C(D)$，且 $f$
74
  分别关于每一单复变量 $z_j (1 <= j <= n)$ 全纯，则 $f in cal(O)(D)$。
75
]
76
// --------- 使用演示 ---------

效果：

在文本中使用美观的大括号分类#

1
#let my-cases = (..items) => box(
2
  baseline: 50% - 0.5em,
3
  width: 1fr,
4
  math.cases(
5
    ..items.pos().map(item => math.display(block(item))),
6
  ),
7
)
8

9
*TEST*: #my-cases(
10
  lorem(20),
11
  lorem(20),
12
  lorem(20),
13
)

效果：

在 Typst 中绘制 LaTeX 符号#

Typst Universe 上有一个现成的包 metalogo，提供了各种 TeX 徽标的绘制函数

其他#

对齐 enum / list 环境中的文本与标号：List and enum markers are not aligned with the baseline of the item’s contents · Issue #1204 · typst/typst

转换为 Markdown#

我的一部分文章使用 Pandoc 将 Typst 转换为 Markdown 文件，方便放在博客。

tip

如果你愿意折腾，可以尝试使用 hexo-renderer-typst 直接在 Hexo 上渲染 Typst 文档。

由于 Typst 0.13 版本已有实验性的 HTML 导出，也可以尝试通过 Typst.ts 进行 HTML 导出。对于 Astro，有可以直接使用 HTML 导出功能渲染为网页的 astro-typst，以及 tinymist 作者编写的基于 Typst 的 Astro 博客模板。

此外，除去 Pandoc，你也可以尝试使用目前集成于 tinymist 内的 typlite 来将 typst 文档转换为 Markdown。

基础操作#

下载 Pandoc 的最新版本，配置相应环境变量（如果有需要的话），然后就可以开始了。

1
pandoc --from=typst --to=markdown --output=path/to/your/blog/source/_draft/post_name.md --wrap=preserve "path/to/your/typst_file.typ"

不能转换的情形#

warning

以下内容基于 pandoc 3.4 说明

import 和 include pandoc 会报错：<stderr>: hPutChar: invalid argument，因此本地包、本地文件和远程包都不能使用。
context pandoc 会报错：<stderr>: hPutChar: invalid argument

可能有更多转换失败的情形，欢迎在本文评论区留言告诉我。

转换可能出现的错误#

与标签相关的内容，转换可能出错
数学公式中未使用括号限制范围的嵌套上下标，转换可能出错，如a_b^c_d（）转换为等

可能有更多转换错误的情形，欢迎在本文评论区留言告诉我。

实用工具#

在线 Typst 公式识别：Typress
在线 Typst 符号手写识别：Detypify（已集成于 Tinymist VSCode 插件中）