Typst 使用

10/29/2023 Typst

# Typst 使用

# 介绍

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

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

目前的大语言模型都没有学习 Typst 内容

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

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

[ ] 数学公式中的两个及以上字符如何使其斜体

# 参考资料

LaTeX 用户指南 – Typst 中文文档 (opens new window)

Typst 中文社区 (opens new window)

Typst 讨论（较活跃）：typst/typst · Discussions · GitHub (opens new window)

# 安装

在线版本：Web - Typst (opens new window)
下载预构建二进制文件 (opens new window)（pre-built binaries）
不同 Linux 发行版 + macOS(brew install typst) + Win(scoop install main/typst)

# 使用

# 实用工具

VSCode 插件：
- typst-lsp：具有语言服务器 + 代码格式化（不再继承）等功能
- typst-preview：实时编译预览
代码格式化：

# 命令行

# 编译
typst compile file.typ  # compile 可简写成 c

# 跟踪文档实时编译
typst watch file.typ    # watch 可简写成 c

# 指定字体搜索路径
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 update

函数定义及使用

命令影响范围

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

# 基础

基础语法概览：Syntax – Typst Documentation (opens new window)

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

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

标记模式：

数学模式：

脚本模式：

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

@fig  // 图片引用

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

// 多图排列
#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>

[x] 强调和加粗对中文字体不起作用（可使用 cuti 包）
有序列表无法使用 markdown 的 1. 格式
换行与转义（Escaping）：使用 \
目录

#outline()

注释

// 单行注释

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

内联代码与代码块：和 markdown 一样，编程语言改成 typ
参考文献及引用

// 方式 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

# 字体

// 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博客 (opens new window)

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

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

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

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

direction

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

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

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

//网格
grid()

// 段落
par()

// 容器
block()

// 表格
table()

pagebreak()

// 文本对齐
align()

// 页面
page()

rect()
// 线条
#line()

// 盒子
box()

// 文本上下标
#sub[]    // 下标
#super[]  // 上标

用法


// 当天日期
#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 (opens new window)
数学字体中的替换字体：Variants Functions – Typst Documentation (opens new window)

// 设置 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 (opens new window) 用于设置文本的字体、大小、颜色和其他属性
page (opens new window) 用于设置页面大小、边距、页眉、启用栏和页脚
par (opens new window) 用于对齐段落、设置行距等
heading (opens new window) 用于设置标题的外观与启用编号
document (opens new window) 用于设置 PDF 输出中包含的元数据，例如标题和作者

#set text(font: "")

# Show 规则

Show 规则用于全局替换

#show

代码块：Code block

内容块：Content block

# 函数

#let function(args) = {}

# 包管理

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

#import "@preview/tablex:0.0.6": tablex, hlinex

未在官网上的，需下载模块源码，以相对路径形式导入（或等待其被官方接受）

#import "mdtable.typ": mdtable

# 推荐 packages

outline 目录：outrageous
绘图（类似 LaTeX 中的 PGF/TikZ）：cetz
box 盒子（类似 LaTeX 中的 colorbox）：showybox
math 数学：physica
table 表格：tablex、tablem
code 代码：codly
note 做笔记：drafting
word count 字数统计：wordometer
图片排版：wrap-it（环绕效果）
checklist：cheq
在 Typst 中使用 LaTeX 公式：MiTeX
中文伪粗体、伪斜体：cuti
presentation 制作：touying (opens new window)、polylux (opens new window)
升级 Typst package：typst-upgrade (opens new window)

cargo install typst-upgrade  # 安装

typst-upgrade .              # 升级
typst-upgrade -d .           # dry run

用 typst 创建 online books：GitHub - Myriad-Dreamin/shiroa: shiroa is a simple tool for creating modern online books in pure typst. (opens new window)

# 相关问题

[x] 标题后首段无法正确缩进：

Behavior of first line indentation in paragraphs seems limiting · Issue #311 · typst/typst · GitHub (opens new window)

首段无法自动缩进 · Issue #12 · shuosc/SHU-Bachelor-Thesis-Typst · GitHub (opens new window)

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

// 解决标题后首段无法正确缩进问题
// 在标题后面添加空白段 使得首段不再是首段
#show heading: it => {
  it
  par(leading: 1.5em)[#text(size:0.0em)[#h(0.0em)]]
}

[ ] 上述方法会出现：列表后的首个段落无法正常缩进

#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 替代工具
[x] 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 中便捷使用伪粗体/伪斜体 (opens new window)

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

Skew transform · Issue #2749 · typst/typst · GitHub (opens new window)

Emphasis does not work for Chinese · Issue #725 · typst/typst · GitHub (opens new window)

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

[ ] 生成的 pdf 如何也有对应的编号（暂无法实现）：Include numbering in PDF bookmark · Issue #2416 · typst/typst · GitHub (opens new window)
[ ] Typst 如何让公式中的单个字符不斜体

LaTeX 使用 Julia 基础

Nobody の博客

Choose mode

Typst 使用

Typst 使用

# Typst 使用

# 介绍

# 参考资料

# 安装

# 使用

# 实用工具

# 命令行

# 基础

# 字体

# 数学公式

# Set 规则

# Show 规则

# 函数

# 包管理

# 推荐 packages

# 相关 project

# 相关问题

Nobody の 博客

Typst 使用

Typst 使用

# Typst 使用

# 介绍

# 参考资料

# 安装

# 使用

# 实用工具

# 命令行

# 基础

# 字体

# 数学公式

# Set 规则

# Show 规则

# 函数

# 包管理

# 推荐 packages

# 相关 project

# 相关问题

Nobody の博客