typst

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Typst

Typst is a modern typesetting system designed as an alternative to LaTeX. It offers a simpler syntax, faster compilation, and programmatic document creation.

Typst是一款现代排版系统，旨在作为LaTeX的替代方案。它拥有更简洁的语法、更快的编译速度，支持程序化创建文档。

Agent Patterns

Agent模式

Detection

检测

bash

typst --version  # Check if installed

bash

typst --version  # Check if installed

Verify Compilation

验证编译结果

Agents cannot preview PDFs. Verify success via exit code:

bash

typst compile document.typ && echo "Success" || echo "Failed"

For text-level verification, see debug.md (

pdftotext

workflow).

Agent无法预览PDF文件。可通过退出码验证是否成功：

bash

typst compile document.typ && echo "Success" || echo "Failed"

如需文本级别的验证，请查看debug.md（

pdftotext

工作流）。

Common Errors

常见错误

Error	Cause	Fix
"unknown variable"	Undefined identifier	Check spelling, ensure `#let` before use
"expected X, found Y"	Type mismatch	Check function signature in docs
"file not found"	Bad import path	Paths resolve relative to the current file
"unknown font"	Font not installed	Use system fonts or web-safe alternatives
"maximum function call depth exceeded"	Deep recursion	Limit recursion, use iteration instead

错误信息	原因	修复方法
"unknown variable"	未定义标识符	检查拼写，确保在使用前用 `#let` 定义
"expected X, found Y"	类型不匹配	查阅文档中的函数签名
"file not found"	导入路径错误	路径相对于当前文件解析
"unknown font"	字体未安装	使用系统字体或网页安全替代字体
"maximum function call depth exceeded"	递归过深	限制递归深度，改用迭代代替

Minimal Document

最小化文档示例

typst

#set page(paper: "a4", margin: 2cm)
#set text(size: 11pt)

= Title

Content goes here.

typst

#set page(paper: "a4", margin: 2cm)
#set text(size: 11pt)

= Title

Content goes here.

Quick Reference

快速参考

Task	Reference
Language basics (types, functions, operators)	basics.md
State, context, query, XML parsing	advanced.md
Templates, styling, set/show rules	template.md
Package development, publishing	package.md
Converting from Markdown/LaTeX	conversion.md
Debugging techniques (pdftotext, repr, measure)	debug.md
Performance profiling (timings, hotspots)	perf.md

任务	参考文档
语言基础（类型、函数、运算符）	basics.md
状态、上下文、查询、XML解析	advanced.md
模板、样式、set/show规则	template.md
包开发、发布	package.md
从Markdown/LaTeX转换	conversion.md
调试技巧（pdftotext、repr、measure）	debug.md
性能分析（计时、热点）	perf.md

When to Use Each Reference

各参考文档适用场景

basics.md

Read first for any Typst work. Complete language reference:

Markup vs code mode switching
Imports and path resolution (relative, root-relative,
```
--root
```
)
All data types and their operations (string, array, dict)
Regex pattern matching
Functions, control flow, operators
Common pitfalls (closure mutability, none returns)

任何Typst工作都应首先阅读。完整的语言参考：

标记模式与代码模式切换
导入与路径解析（相对路径、根相对路径、
```
--root
```
参数）
所有数据类型及其操作（字符串、数组、字典）
正则表达式匹配
函数、控制流、运算符
常见陷阱（闭包可变性、空返回值）

advanced.md

For cross-document features and complex patterns:

State management (
```
state()
```
,
```
context
```
)
Query system (
```
query()
```
, metadata, labels)
XML parsing
Working around closure limitations
Performance optimization

适用于跨文档功能与复杂模式：

状态管理（
```
state()
```
、
```
context
```
）
查询系统（
```
query()
```
、元数据、标签）
XML解析
闭包限制的解决方法
性能优化

template.md

For document templates and styling:

Set rules (defaults) and show rules (transformations)
Page layout, headers, footers
Counters and numbering
Heading and figure customization

适用于文档模板与样式设计：

Set规则（默认值）与Show规则（转换）
页面布局、页眉、页脚
计数器与编号
标题与图表自定义

package.md

For creating reusable Typst packages:

```
typst.toml
```
manifest format
Module organization and imports
API design patterns
Publishing to Typst Universe

适用于创建可复用的Typst包：

```
typst.toml
```
清单格式
模块组织与导入
API设计模式
发布到Typst Universe

conversion.md

For converting existing documents to Typst:

Syntax mapping tables (Markdown/LaTeX → Typst)
Math formula conversion
Escaping rules
Pandoc integration

适用于将现有文档转换为Typst：

语法映射表（Markdown/LaTeX → Typst）
数学公式转换
转义规则
Pandoc集成

debug.md

For debugging Typst documents (especially for agents):

```
pdftotext
```
for text content verification
```
repr()
```
for inspecting complex objects
```
measure()
```
+
```
place()
```
for layout debugging
State and query debugging patterns

适用于调试Typst文档（尤其针对Agent）：

使用
```
pdftotext
```
验证文本内容
使用
```
repr()
```
检查复杂对象
使用
```
measure()
```
+
```
place()
```
调试布局
状态与查询调试模式

perf.md

For performance profiling and timing analysis:

```
--timings
```
JSON trace output
Aggregating hotspots from trace events
Viewing traces in Chrome/Perfetto

适用于性能分析与计时分析：

```
--timings
```
JSON跟踪输出
从跟踪事件中聚合热点
在Chrome/Perfetto中查看跟踪信息

Compilation

编译命令

bash

undefined

bash

undefined

Compile once

编译一次

typst compile document.typ

Watch mode (recompile on changes)

监听模式（文件变更时重新编译）

typst watch document.typ

Specify output file

指定输出文件

typst compile document.typ output.pdf

Set project root (for multi-file projects)

设置项目根目录（适用于多文件项目）

Root controls where "/path" resolves and security boundary

根目录控制"/path"的解析位置与安全边界

typst compile src/main.typ --root .


**When to use `--root`**: If your document imports files using `/`-prefixed paths (e.g., `#import "/lib/utils.typ"`), set `--root` to the directory those paths should resolve from. See [basics.md](basics.md) for path resolution rules.

typst compile src/main.typ --root .


**何时使用`--root`**：如果你的文档使用以"/"开头的路径导入文件（例如`#import "/lib/utils.typ"`），请将`--root`设置为这些路径应解析到的目录。路径解析规则详见[basics.md](basics.md)。

Common Packages

常用包

Package	Purpose
`@preview/codly`	Code block formatting with syntax highlighting
`@preview/ctheorems`	Theorem environments
`@preview/mitex`	LaTeX math rendering
`@preview/cuti`	CJK typography utilities
`@preview/citegeist`	BibTeX parsing

Import packages (check https://typst.app/universe for latest versions):

typst

#import "@preview/codly:1.3.0": *

包名称	用途
`@preview/codly`	带语法高亮的代码块格式化
`@preview/ctheorems`	定理环境
`@preview/mitex`	LaTeX数学公式渲染
`@preview/cuti`	CJK排版工具
`@preview/citegeist`	BibTeX解析

导入包（查看https://typst.app/universe获取最新版本）：

typst

#import "@preview/codly:1.3.0": *

Examples

示例

The

examples/

directory contains runnable examples:

Example	Description
basic-document.typ	Complete beginner document with all common elements
template-report.typ	Reusable template with headers, counters, note boxes
package-example/	Minimal publishable package with submodules

examples/

目录包含可运行的示例：

示例	描述
basic-document.typ	包含所有常见元素的完整入门文档
template-report.typ	带页眉、计数器、注释框的可复用模板
package-example/	包含子模块的最小可发布包

Dependencies

依赖

typst CLI: Install from https://typst.app or via package manager
- macOS:
```
brew install typst
```
- Linux:
```
cargo install typst-cli
```
- Windows:
```
winget install typst
```

typst CLI：从https://typst.app或包管理器安装
- macOS:
```
brew install typst
```
- Linux:
```
cargo install typst-cli
```
- Windows:
```
winget install typst
```