typst 是做什么的？
Typst 是一个基于标记的排版系统，内置脚本语言。单个二进制文件可将 .typ 编译为 PDF（默认）、PNG、SVG、HTML（实验性）或多文件包（实验性）。本技能针对 Typst 0.15.x（已验证至 0.15.1）；附注中会标明旧版本中不同的行为。
关于 Typst 的训练数据通常过时（0.11–0.13 版本）。当不确定某个函数、参数或默认值时，请查阅
references/api-signatures.md，然后编译探针（typst eval '<expr>'或 5 行文件），而不是猜测。
工作流程
- 明确输出：PDF（默认）、HTML、PNG/SVG、可访问 PDF（PDF/UA）、存档 PDF（PDF/A）？页面大小、语言、字体、引用样式、模板/期刊？
- 从骨架（见下文）或
examples/开始。对于期刊/论文/简历/幻灯片，首先搜索包：python3 scripts/search-packages.py "ieee paper"（参见references/packages-and-ecosystem.md）。 - 编写文件：将
set/show规则和导入放在顶部，内容放在下方。使用#include和#import拆分大型项目。 - 编译和检查：
typst compile main.typ— 读取诊断信息（它们包含行:列和提示）。通过 PNG 进行视觉验证（typst compile main.typ 'p-{p}.png'），或通过typst compile main.typ - -f html --features html/pdftotext进行文本验证。详细信息见references/pitfalls-and-debugging.md。 - 格式化（如果可用）：
typstyle -i file.typ。仅当差异仅限于您自己的编辑时。 - 报告哪些文件已创建/更改以及如何重建。
最小骨架
#set document(title: "My Document", author: "Name")
#set page(paper: "a4", margin: 2.5cm, numbering: "1")
#set text(font: "New Computer Modern", size: 11pt, lang: "en")
#set par(justify: true, leading: 0.65em)
#set heading(numbering: "1.1")
#title()
= Introduction <intro>
Typst supports *bold*, _italic_, `raw`, math $E = m c^2$ and references like @intro.
== A subsection
#lorem(30)
$ integral_0^1 x^2 dif x = 1/3 $
始终安全的默认值：#set text(lang: "...")（断字、引号、补充、可访问性）、#set document(title: ...) + #title() 用于可见标题、#set par(justify: true) 用于正文。
60 秒语法速览
| 模式 | 输入方式 | 示例 |
|---|---|---|
| Markup（默认） | — | = Heading, *strong*, _emph_, - item, + numbered, / Term: desc, @label, <label> |
| Code（代码） | #（一个表达式）或 #{ ... } 块 | #let x = 3, #f(1)[body], #if a [yes] else [no], #for i in range(3) [#i ] |
| Math（数学） | $...$（$ x $ 带空格 = 独立行） | $a^2 + b_i$, $sum_(i=1)^n i$, $ vec(1, 2) $ |
| Content block（内容块） | 代码内使用 [...] | #box[hi], let c = [*x*] |
- 在代码中，不要重复
#：#figure(image("a.png"), caption: [Hi])。在[...]内容块内部，您会回到 markup 模式：[Total: #x]。 - 数组
(1, 2)，字典(a: 1, b: 2)，空()/(:)，单元素(1,)。没有元组。使用.at(i)索引，而不是[i]。 - 命名参数使用
:（f(width: 2cm)）；=仅在let/代码内是赋值。 - 字符串
"..."，内容[...]，原始`...`。使用str(x)、[#s]、eval(s, mode: "markup")进行转换。 - 注释：
// line，/* block */。使用\转义特殊字符（\#、\$、\@、\*、\_、\<）；Unicode\u{1F600}。 - 长度单位：
pt mm cm in em、fr（分数）、%、角度deg rad。auto和none是值。 set= 从这里开始为某个元素设置默认参数；show= 重新样式化/替换元素。context是读取样式/计数器/位置所必需的（参见references/introspection.md）。- 路径：仅使用正斜杠（0.15 版本）。
"/x.typ"是项目根目录相对路径（默认根目录：主文件所在目录；使用--root更改），"x.typ"是当前文件相对路径。 - 方法语法随处可见：
"abc".len()、(1,2,3).map(x => x*2)、rgb("#f00").lighten(30%)。
查阅指南
| 需求 | 查阅 |
|---|---|
语法、类型、运算符、字符串/数组/字典方法、模块、闭包、context 基础 | references/syntax-and-scripting.md |
set/show 规则、选择器、页面设置、文本、段落、块、网格、分栏、对齐、间距、定位、变换 | references/styling-and-layout.md |
| 标题、列表、图形、表格、参考文献、脚注、大纲、引用、书目/引文/CSL、编号、链接、元数据 | references/document-model.md |
| 方程、数学语法、符号、矩阵、对齐、字体、编号 | references/math.md |
| 形状、曲线、图像、颜色、渐变、填充、描边、专色 | references/visuals.md |
计数器、状态、query、locate、metadata、within、布局收敛、页眉、measure/layout | references/introspection.md |
CSV/JSON/YAML/TOML/XML/CBOR、read、bytes、sys.inputs、eval、WASM 插件、数据驱动文档 | references/data-and-io.md |
CLI 标志、字体、PDF/A/UA、可访问性、HTML、包、PNG/SVG、typst eval、CI/可重现构建 | references/export-and-cli.md |
| 幻灯片（Touying/Polylux、动画、讲义、演讲者备注、pdfpc） | references/slides.md |
模板、typst.toml、发布包、Universe 包选择（cetz, fletcher, touying, codly, ...）、编辑器工具 | references/templates-and-packages.md、references/packages-and-ecosystem.md |
| LaTeX → Typst 转换、Markdown/pandoc 转换、从 0.11–0.14 升级 | references/migration.md |
| 错误、警告、探针、视觉验证、性能、常见陷阱 | references/pitfalls-and-debugging.md |
| 每个元素的确切参数/默认值（已验证至 0.15.1 源代码） | references/api-signatures.md |
| 即编即用的入门文件 | examples/*.typ |
主要陷阱（写作前请阅读）
- set/show 规则向前应用，且仅在其作用域内生效；将它们放在应影响的内容之前。
[...]/{...}内的set随块结束。 - 读取任何依赖于位置/样式的内容需要
context：#context counter(page).get()、#context text.size。否则："只能在上下文已知时使用"。 - 闭包捕获的变量是只读副本；通过
fold、单个代码块内的循环、state或counter进行累积。 #只需要一次；在标记中，对于包含运算符的表达式，使用#(a + b)；#f(x).g有效，但#f (x)（空格）不会调用。- 数学不是文本：多字母单词是符号/变量（
alpha、sin）；将文本写作"text"或upright(...)。单个字母是斜体变量。 - 字符串不是内容：标题主体是内容；使用
.body、str()或辅助函数to-string（参见语法参考）获取文本。 - 字体：只有已安装/嵌入/
--font-path的字体可用；未知字体名仅会警告并回退。使用typst fonts列出。对于可变字体，省略名称中的 "Variable"/"VF"（0.15 版本）。 - 包使用精确版本导入：
#import "@preview/cetz:0.5.3"— 请查阅 Typst Universe（scripts/search-packages.py）获取最新版本，而不是依赖记忆。包可能落后于新编译器。 - 0.15 版本的移除项：
path()→curve()、pattern→tiling、pdf.embed→pdf.attach、*.decode(...)→ 将bytes传递给json(...)等、typst query→typst eval、路径中不允许反斜杠。 - HTML/包导出是实验性的，需要
--features html/--features bundle。
快速习语
// 可重用模板：使用函数和 show 规则
#let conf(title: none, authors: (), body) = {
set page(margin: 2cm)
set par(justify: true)
align(center, text(17pt, weight: "bold", title))
v(1em)
body
}
#show: conf.with(title: [My Paper])
// 为某个标题级别设置样式
#show heading.where(level: 1): set text(navy)
#show heading.where(level: 1): it => block(above: 1.5em, below: 1em, it)
// 交叉引用和图形
#figure(table(columns: 2, [A], [B], [1], [2]), caption: [Data]) <tab:data>
See @tab:data.
// 数据驱动内容
#for (name, score) in (("Ann", 3), ("Bo", 5)) [- #name: #score]
// 从 CLI 运行时输入：typst compile --input mode=draft main.typ
#let draft = sys.inputs.at("mode", default: "final") == "draft"
编译速查表
typst compile main.typ # → main.pdf
typst compile main.typ out.pdf --root .
typst compile main.typ 'page-{0p}.png' --ppi 144
typst watch main.typ # 更改时重新编译
typst eval 'calc.pow(2, 10)' # 计算表达式，JSON 输出
typst eval --in main.typ 'query(heading).len()'
typst init @preview/charged-ieee # 从模板创建新项目
typst fonts --variants # 已安装字体
示例（均在 0.15.1 上编译）
| 文件 | 展示内容 |
|---|---|
examples/memo.typ | 简短备忘录，标题网格，简单样式 |
examples/report.typ | 标题页、目录、页眉、图形/表格/脚注、show 规则 |
examples/academic-paper.typ (+ refs.bib) | 方程、定理环境、交叉引用、引文 |
examples/data-report.typ (+ data.csv) | CSV → 表格、计算列、--input、简单形状柱状图 |
examples/template.typ + template-usage.typ | 可重用模板函数 + 组件 |
examples/accessible.typ | PDF/A-2a + PDF/UA-1（--pdf-standard a-2a,ua-1） |
examples/dual-target.typ | 同一源文件 → PDF 和 HTML（context target()、html.*） |
examples/query-export.typ | metadata + typst eval 结构导出 |
examples/slides-plain.typ、examples/letter.typ | 无包的幻灯片和正式信函 |
examples/packages-demo.typ | cetz、fletcher、lilaq、theorion、codly（锁定版本，已验证） |
脚本
scripts/check-snippets.py FILE.md…— 编译每个```typ代码块（使用```typ-x标记仅供说明/不可编译的块）。在您编写的任何包含 Typst 的 Markdown 上运行。scripts/search-packages.py "keywords" [--category cv] [--name cetz --versions]— 查询 Typst Universe 索引以获取当前包名称/版本。