Post

Typst 使用

Posted Updated
By Nobody 18 min read

Typst 使用

介绍

Typst 是一门用于文档排版的标记语言。

Typst 优势：语法简单、编译速度快（毫秒级别）、环境搭建简单，详细使用体验，参见：Typst 中文用户使用体验 - OrangeX4 - 知乎

1
2
3
4
5
6
7
8
9
10
11
12

// 页脚设置
// 方式 1
#set page(numbering: "1/1")

// 方式 2
#set page(
  footer: context {
    set align(center)
    set text(9pt)
    counter(page).display()
  }
)

参考资料

安装

1
2

brew install typst         # macOS
scoop install main/typst   # Win

使用

工具

  • VSCode 插件：
    • typst-lsp：具有语言服务器 + 代码格式化（不再继承）等功能
    • tinymist：代码格式化
  • typst-upgrade：检查并升级 Typst packages
1
2
3
4
5

cargo install typst-upgrade  # 安装

# file.typ 可改成 .
typst-upgrade file.typ       # 更新 package 并写入文件
typst-upgrade -d file.typ    # --dry-run 不实际运行

命令

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

# 编译
typst compile file.typ  # 或 typst c

# 跟踪文档实时编译
typst watch file.typ    # 或 typst w

# 指定字体搜索路径
typst compile file.typ --font-path path/to/fonts

# 列出系统和给定目录中发现的所有字体
typst fonts --font-path path/to/fonts

# 设置字体环境变量
TYPST_FONT_PATHS=path/to/fonts typst fonts

# 指定 project 路径
typst compile file.typ --root ..

# 更新 typst 版本
typst update

函数定义及使用

命令影响范围

#text(weight: "bold")[bold text] 将只对其参数加粗， 而 #set text(weight: "bold") 将对当前块或直到文件结尾之前的所有文本加粗。

基础

image.png

image.png

三种语法模式：标记、数学和脚本

Typst 为常用文档元素内置了语法标记，大多只是对应函数的快捷表达方式

标记模式：

image.png

数学模式：

image.png

脚本模式：

image.png

image.png

  • 图片插入及引用：figure 及 image 函数
    • image 函数支持的图片格式：png、jpg、gif、svg，不支持 tiff
    • 不支持根目录的绝对路径？
1
2
3
4
5
6

@fig  // 图片引用

#figure(
   image("fig.png"),
   caption: [ Caption ],
) <fig>

1
2
3
4
5
6
7
8
9
10
11

// 多图排列
#figure(
  grid(
    columns: 2,
    row-gutter: 2mm,
    column-gutter: 1mm,
    image("assets/Nb5Si3_1.png"), image("assets/Nb5Si3_1.png"), 
    image("assets/Nb5Si3_3.png"), image("assets/Nb5Si3_4.png"), 
  ),
  caption: "Caption"
) <Nb5Si3_plot>
  • 强调和加粗对中文字体不起作用（可使用 cuti 包）

  • 有序列表无法使用 markdown 的 1. 格式

  • 换行与转义（Escaping）：使用 \

  • 目录
1

#outline()
  • 注释
1
2
3
4
5
6

// 单行注释

/*
多行注释
多行注释
*/

  • 内联代码与代码块：和 markdown 一样，编程语言改成 typ

  • 参考文献及引用

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

// 方式 1
@ZHU2023119062

// 方式 2
#cite(<ZHU2023119062>) \
#cite(<ZHU2023119062>, form: "prose") \
#cite(label("ZHU2023119062"))

#bibliography(
  "refs.bib",
  title: "参考文献",
  style: "gb-7714-2015-numeric",
  // style: "american-physics-society",
  // style: "nature",
)
  • 参考文献 style 推荐：
    • gb-7714-2015-numeric（暂无自定义不显示参考文献特定内容，如 doi 的功能，BibTeX 可以）
    • american-physics-society
    • nature
    • ieee
    • american-chemical-society

字体

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39

// reference: https://github.com/lucifer1004/pkuthss-typst/blob/main/template.typ
#let 字号 = (
  初号: 42pt,
  小初: 36pt,
  一号: 26pt,
  小一: 24pt,
  二号: 22pt,
  小二: 18pt,
  三号: 16pt,
  小三: 15pt,
  四号: 14pt,
  中四: 13pt,
  小四: 12pt,
  五号: 10.5pt,
  小五: 9pt,
  六号: 7.5pt,
  小六: 6.5pt,
  七号: 5.5pt,
  小七: 5pt,
)

#let 字体 = (
  仿宋: ("Times New Roman", "FangSong"),
  宋体: ("Times New Roman", "SimSun"),
  黑体: ("Times New Roman", "SimHei"),
  楷体: ("Times New Roman", "KaiTi"),
  代码: ("New Computer Modern Mono", "Times New Roman", "SimSun"),
  得意黑: ("Smiley Sans",),
)


// https://github.com/OrangeX4/Chinese-Resume-in-Typst/blob/main/template.typ
#let font = (
  main: "IBM Plex Serif",
  mono: "IBM Plex Mono",
  cjk: "Noto Serif CJK SC",
)

set text(font: (font.main, font.cjk), size: 10pt, lang: "zh")

字体 stroke 指字体的描边，含描边颜色、宽度、线条样式和透明度

TeX Gyre Termes：基于 Times Roman 的衬线字体，Noto Serif CJK SC：专为简体中文设计的衬线字体

1em：quad，相对单位；定义为当前字体大小的宽度；常用场景：缩进，段落、表格间距

1ex：相对单位，等于当前字体中小写字母 x 的高度；常用于垂直方向上的间距调整

1pt：point，绝对单位；在 TeX 系统中，1pt = 1/72.27 英寸（大约 0.35146 毫米）；常用场景：字体大小，精确间距，线条和边框

Word 中的字符度量单位：1 磅值 = 1/72 in = 1bp = 1.00375 pt

浅谈LaTeX与Word度量单位对应关系_letex和word页边距转换-CSDN博客

smartquote（智能引号）：根据文本语言（英、德、法语等）自动选择适当的开闭引号形式

smallcaps(small capitals)：小型大写字母的字体格式，小写字母以小号的大写字母形式显示，但与真正的大写字母相比，它们的尺寸稍微小一些；LaTeX 对应命令为 \textsc{}

对齐 align 函数 可选参数值：start、end、left、right、center、top、horizon、bottom 可以使用两个参数值，用 +

1

#set align(center + horizon)  // 在表格中，位于单元格中心位置

direction

1
2
3
4

ltr: Left to right.
rtl: Right to left.
ttb: Top to bottom.
btt: Bottom to top.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

fr // 分数
h() // 水平间距
v() // 垂直间距

// 水平或垂直排列内容和间距
stack()

//网格
grid()

// 段落
par()

// 容器
block()

// 表格
table()

pagebreak()

// 文本对齐
align()

// 页面
page()

rect()
// 线条
#line()

// 盒子
box()

// 文本上下标
#sub[]    // 下标
#super[]  // 上标
  • 用法
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

// 当天日期
#datetime.today().display("[year]年[month]月[day]日")

// reference: https://typst.app/project/rI2NZaeIAMwgmyBXnz6tdF
#set par(
  justify: true,
  first-line-indent: 2em,  // 首行缩进
  leading: 20pt,   // 行距 20 磅
)

#show par: set block(spacing: 20pt) // 段间距 20 磅

#set text(
  // 正文小四号字，英文用 Times Roman，中文用宋体
  size: 12pt,
  font: (
    "TeX Gyre Termes", 
    "Noto Serif CJK SC",
  ),
  lang: "zh"
)

数学公式

  • 公式中的文本：若涉及到 typst 中的关键字，可以用 "" 包裹文本
  • 数学公式设置：等式：#set math.equation()；矩阵：#set math.mat()
  • 与 LaTeX 不同，symbols 前不需加 \
  • 分数：1/2 或 frac(a, b)
  • root 根：平方根：sqrt(2)，非平方根：root(N, x)
  • 分隔符匹配：分隔符大小与内容保持一致，类似 LaTeX 中的 \left、\right；lr()、mid()、abs()、ceil()、floor()、round()、norm()
  • 向量：vec()，矩阵：mat()
  • 箭头：arrow()
  • 上、下划线：underline()、overline()、underbrace()、overbrace()

  • Typst 符号 General Symbols

  • 数学字体中的替换字体：Variants Functions – Typst Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

// 设置 math 字体
#show math.equation: set text(font: "Times New Roman")
// 设置 code 字体
#show raw: set text(font: "Fira Code")

// 数学公式编号，在引用的编号之前添加 supplement 内容
#set math.equation(numbering: "(1)", supplement: [Eq.])

// 行内公式 公式与 $$ 之间无空格
$Q = rho A v + C$

// 行间公式 公式与 $$ 之间有空格 <eq1> 公式标签
$ 7.32 beta + sum_(i=0)^nabla Q_i / 2 $ <eq1>

// 公式引用
@eq1

// 分隔符匹配
$
abs(a + b), norm(a + b), floor(a + b), ceil(a + b), round(a + b)
$

// 向量
$
vec(a, b, c) + vec(1, 2, 3) = vec(a + 1, b + 2, c + 3)
$

// 矩阵
$
mat(
    1, 2, ..., 10;
    2, 2, ..., 10;
    dots.v, dots.v, dots.down, dots.v;
    10, 10, ..., 10; // `;` in the end is optional
)
$

Set 规则

Set 规则可以设置样式，为函数设置参数默认值

Set 规则中常用的一些函数的列表：

  • text 用于设置文本的字体、大小、颜色和其他属性
  • page 用于设置页面大小、边距、页眉、启用栏和页脚
  • par 用于对齐段落、设置行距等
  • heading 用于设置标题的外观与启用编号
  • document 用于设置 PDF 输出中包含的元数据，例如标题和作者
1

#set text(font: "")

Show 规则

Show 规则用于全局替换

1

#show

代码块：Code block

内容块：Content block

函数

1

#let function(args) = {}

包管理

  • 包可以是 package，也可以是 template
  • 已在官网上的 packages，以 #import "@preview/pkg:1.0.0" 格式导入，编译时会自动下载和自动导入 packages
1

#import "@preview/tablex:0.0.6": tablex, hlinex
  • 未在官网上的，需下载模块源码，以相对路径形式导入（或等待其被官方接受）
1

#import "mdtable.typ": mdtable

推荐 packages

其他

模板

相关问题

1
2
3
4
5
6
7
8
9
10
11

#set par(
  first-line-indent: 2em,
  justify: true,
)

// 解决标题后首段无法正确缩进问题
// 在标题后面添加空白段 使得首段不再是首段
#show heading: it => {
  it
  par(leading: 1.5em)[#text(size:0.0em)[#h(0.0em)]]
}
  • 上述方法会出现：列表后的首个段落无法正常缩进
  • 中文目录设置
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

#import "@preview/outrageous:0.1.0"

// 目录设置
#let ChineseOutline() = {
  set align(center)
  set text(font: 字体.宋体, size: 字号.小四)
  set page(numbering: "I")
  counter(page).update(1)
  set par(
    justify: true,
    first-line-indent: 2em,
  )

  // 一级目录字体、间距设置
  show outline.entry.where(
    level: 1
  ): it => {
    set text(size: 字号.中四)
    v(2pt)
    strong(it)
  }

  // outrageous 目录设置
  show outline.entry: outrageous.show-entry.with(
    ..outrageous.presets.typst,
    fill: (none, auto),
  )

  outline(
    title: text("目录"), 
    indent: 1em,
  )

  pagebreak(weak: true)

}

  • Typst 中暂无 latexdiff 替代工具

  • Mac 中的 VSCode typst preview 无法处理相对路径情况 #import "../template.typ": *，会报错（应该是 bug，已修复）；windows 上的正常

  • 自己电脑的中文字体在 Typst 已是加粗 bold 状态，如何恢复 regular

[GitHub - csimide/cuti: Cuti: A simple typst package simulates fake bold / fake italic characters. Cuti：在 typst 中便捷使用伪粗体/伪斜体](https://github.com/csimide/cuti)

Fake text weight and style (synthesized bold and italic) · Issue #394 · typst/typst · GitHub

Skew transform · Issue #2749 · typst/typst · GitHub

Emphasis does not work for Chinese · Issue #725 · typst/typst · GitHub

lexer change: Allow emphasis in CJK text without spaces by peng1999 · Pull Request #2648 · typst/typst · GitHub

排版语言
Typst
This post is licensed under CC BY 4.0 by the author.