typst

Typst

此技能适用于 Typst 0.15+。对于 Typst 0.14.2，请使用上一个技能快照对应的 typst-0.14.2 仓库标签。

编译

typst compile document.typ              # compile once → PDF
typst compile document.typ output.pdf   # explicit output path
typst compile document.typ -f png       # export as PNG image
typst compile src/main.typ --root .     # set project root for /path imports
typst watch document.typ                # recompile on change
typst eval --in document.typ 'query(heading).len()'  # Typst 0.15+ introspection

有关此快速参考之外的命令选项，请参阅 cli.md。

Agent 验证——根据需要检查的内容选择（详情请参阅 debug.md）：

方法	命令	最适合检查
HTML 导出	typst compile doc.typ /dev/stdout -f html --features html 2>/dev/null	文本内容、结构、标题、表格
PNG 导出	typst compile doc.typ page-{p}.png -f png	视觉布局、对齐、间距、字体
pdftotext	typst compile doc.typ && pdftotext doc.pdf -	特定页面内容的备用方案

最小文档

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

= Title

Content goes here.

编写文档

要开始编写新文档？ 从下方的 示例 中复制最接近的配方——这比从空白文档开始更快，而且每一行都标明了接下来要阅读的文档。

需要……	阅读
学习语法、导入、函数、控制流	basics.md
学习数据类型、运算符、字符串/数组方法	types.md
设置页面、标题、图形和布局样式	styling.md
表格、网格、单元格跨列、边框、数据表	tables.md
学术论文、参考文献、定理、公式	academic.md
从 Markdown 或 LaTeX 转换	conversion.md
升级旧版 Typst 代码，了解 0.15 版不兼容变更	migration.md
使用 Typst CLI 命令和构建选项	cli.md
从文档中提取数据、多轮构建	query.md

开发包和模板

需要……	阅读
状态、计数器、文档内的 query()、XML	advanced.md
CLI 内省、元数据导出、多轮构建	query.md
创建可复用的模板函数	template.md
创建或发布软件包	package.md
验证输出（HTML/PNG/pdftotext、repr）	debug.md
分析性能（--timings、热点）	perf.md

basics.md 和 types.md 也是开发者的基础。

查找软件包

搜索 Typst Universe 软件包的内嵌索引（每周更新）：

python3 scripts/search-packages.py "what you need"
python3 scripts/search-packages.py "chart" --category visualization
python3 scripts/search-packages.py --category cv --top 5
python3 scripts/search-packages.py --list-categories

常见错误

错误	原因	修复方法
"unknown variable"	标识符未定义	检查拼写，并确保在使用前有 #let
"expected X, found Y"	类型不匹配	查看文档中的函数签名
"file not found"	导入路径错误	路径相对于当前文件解析
"unknown font"	未安装字体	使用系统字体或适合 Web 的替代字体
"maximum function call depth exceeded"	递归过深	改用迭代
"can only be used when context is known"	缺少 context 包装器	用 context { ... } 包装
"unexpected argument"	参数使用了 = 而非 :	命名参数使用 : 语法：func(name: value)
"variables from outside are read-only"	修改捕获的变量	使用循环累积或 state() — 参见 advanced.md
"expected content, found string" (or vice versa)	内容/字符串类型不匹配	使用 [#str-var] 将字符串嵌入内容
set/show 规则不起作用	规则放在内容之后	将 set/show 规则放在其目标内容之前

示例

复制最接近的起始示例，进行调整并编译。对于简历、信件或幻灯片，请搜索软件包：python3 scripts/search-packages.py --category cv（或 letter、presentation）。

示例	适用于……	接下来阅读
basic-document.typ	简短便笺或备忘录	basics.md、styling.md
styled-document.typ	带页面样式的多章节报告	styling.md、tables.md
template-report.typ	可重复用于一系列文档的模板	template.md
tables-showcase.typ	数据密集型文档（表格、CSV/JSON）	tables.md、types.md
academic-paper.typ	带引用、定理和数学内容的论文	academic.md
query-export.typ	元数据导出或多轮构建	query.md
package-example/	可发布的软件包	package.md

依赖项

• 推荐使用 typst CLI 0.15+：从 https://typst.app 安装，或通过软件包管理器安装
  • macOS：brew install typst
  • Linux：cargo install typst-cli
  • Windows：winget install typst
• pdftotext（可选）：用于验证文本级输出
• Python 3.10+（可选）：用于软件包搜索和验证脚本
• jq（可选）：用于在 shell 脚本中解析 typst eval 的 JSON 输出

API 参考搜索

搜索 Typst API 函数、方法和构造函数的内嵌索引：

python3 scripts/search-api.py "image width fit"
python3 scripts/search-api.py "color lighten" --kind method
python3 scripts/search-api.py --name str.position -v
python3 scripts/search-api.py "rightarrow" --kind symbol   # LaTeX names work
python3 scripts/search-api.py --list-categories

生态系统工具

生态系统工具：tinymist（LSP/编辑器）、typstyle（格式化工具）、typst-package-check（软件包验证器）、tytanic（视觉测试运行器）。有关软件包工具的详细信息，请参见 package.md。