# Typst Writing Conventions > 当编辑/创建 .typ 文件时，必须使用本技能以确保符合 Typst 语法规范（如 subset→subset.eq, \sigma→sigma, integral→integral 等）、符号映射规则、文档层级结构和写作风格约定。尤其适用于新增数学公式较多的笔记时。 - Skill: `locusyuri/typst-writing-conventions` (Agent Skill) - Install (CLI): `npx skillmds@latest add locusyuri/typst-writing-conventions` - Raw SKILL.md: https://api.skillmd.com/api/skills/locusyuri/typst-writing-conventions/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: locusyuri (https://skillmd.com/u/locusyuri) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/locusyuri/typst-writing-conventions --- ## 1. 文档结构 ### 层级体系 | 语法 | 层级 | 含义 | |------|------|------| | `#part("...")` | Part | 大知识模块分组 | | `= ...` | Chapter（一级标题） | 完整知识单元 | | `== ...` | Section（二级标题） | 章内主要知识点 | | `=== ...` | Subsection（三级标题） | 节内细分 | ### 标题规则 - 标题标记 `=` 后必须有空格：`= Title`（正确）vs `=Title`（错误） - 不要跳级使用标题（如从 `=` 直接到 `===`） --- ## 2. 文本格式 | 效果 | 语法 | |------|------| | 加粗 | `*text*` | | 斜体 | `_text_` | | 行内代码 | `` `code` `` | | 脚注 | `#footnote[...]` | | 垂直间距 | `#v(1cm)` | | 行内高亮 | `#highlight[text]` | ### 列表 - 无序列表：`- item` - 有序列表：`1. item` / `2. item` - 嵌套：使用缩进（Tab 或两空格） --- ## 3. 数学公式 ### 基本用法 - 行内公式：`$ ... $`（与文本同行） - 行间公式（display math）：`$ ... $`（单独成段，前后有空行或换行） ### 符号映射（LaTeX → Typst） | LaTeX | Typst | |-------|-------| | `\mathbb{R}` | `bb(R)` | | `\mathcal{F}` | `cal(F)` | | `\mathscr{M}` | `scr(M)` | | `\to`, `\rightarrow` | `->` | | `\Rightarrow` | `=>` | | `\Leftrightarrow` | `<=>` | | `\infty` | `oo` | | `\subseteq` | `subset` | | `\cup` | `union` | | `\cap` | `inter` | | `\notin` | `in.not` | | `\neq` | `!=` | | `\land` | `and` | | `\lor` | `or` | | `\lnot` | `not` | | `\circ`（复合） | `compose` | | `\preceq` | `prec.eq` | | `\oplus`（对称差） | `plus.o` | | `\forall` | `forall` | | `\exists` | `exists` | | `\partial` | `partial` | | `\mathrm{d}x` | `dif x` | | `\liminf` | `liminf` | | `\limsup` | `limsup` | | `\sup` | `sup` | | `\inf` | `inf` | | `\overline{X}` | `overline(X)` | | `\chi_A`（特征函数） | `chi_A` | | `\backslash` | `backslash` | | `\int` | `integral` | | `\iint`, `\iiint` | `integral.double`, `integral.triple` | | `\oint` | `integral.cont`（闭合环路线积分） | | `\cdot` | `dot` | | `\sim` | `~` 或 `approx` | | `\text{...}` | `text("...")`（**必须用字符串引号**） | | `\left(`, `\right)` | 无对应命令，Typst 自动缩放括号 | | `\left[`, `\right]` | 无对应命令，Typst 自动缩放方括号 | ### 硬规则（必须遵守） 1. **不属于符号**：写 `$in.not$`，不要写 `$notin$` 2. **子集**：统一写 `$subset$` 3. **箭头**：`$->$`、`$<=>$`，不保留 LaTeX 宏名 4. **不等于**：`$!=$`（注意空格：`$!= $` 或 `$a != b$`） 5. **函数复合**：`$compose$` 6. **微分符号**：使用正体 `dif x`、`dif t` 7. **导数点记号**：`dot(x)`、`dot.double(x)`、`dot.triple(x)` 8. **积分号**：用 `integral`，不是 `int`。二重/三重：`integral.double`、`integral.triple` 9. **`text()` 必须用字符串参数**：写 `text("something")`，不是 `text(something)` 10. **点乘**：写 `a dot b`，不用 `a cdot b`（`cdot` 不存在） 11. **`\left(`/`\right)` 不存在**：Typst 自动缩放括号，不需要 `\left`/`\right` ### 常见陷阱 #### 裸下标问题 Typst 不支持 `$_x$`，下标 `_` 前必须有主体。 ```typst // 错误 $_x$ // 正确：空主体下标 $""_x$ ``` #### 多字母变量问题 Typst 将连续字母识别为内置函数名（如 `sin`、`exp`），或把相邻的单字母变量合并为一个未知多字母变量，导致编译错误。 ```typst // 正体多字母变量：用引号包裹 $"ext"$, $"const"$, $"max"$ // 斜体多字母变量：用空格分开 $e x t$ // 示例 $bold(F)_i^("ext")$ // 外力 ``` **相邻单字母变量之间必须用空格分隔**，否则整体被识别为一个未知变量（报 `unknown variable: xy` 等）： ```typst // 错误 — 字母连写被合并为单个未知变量 $xy$ // → unknown variable: xy $2xy$ // → unknown variable: xy $2 x y z$ 若写成 $2xyz$ // 正确 — 变量与变量之间留空格 $x y$ $2 x y$ ``` 数字紧跟单个变量（如 `$2x$`）本身合法，但建议统一写成 `$2 x$` 保持风格一致。 **排查指南**：遇到 `unknown variable` 错误时，优先排查两类根因——多字母连写（如 `xy`、`2xy`）与 LaTeX 宏残留（如 `cdot`、`int`、`infty`）。 #### 组件参数中的引号嵌套 组件的 `name:` / `title:` 等字符串参数内部**不能直接嵌套双引号**，否则字符串提前终止，报 `unclosed delimiter` / `expected comma`： ```typst // 错误 — 内层双引号截断了外层字符串 #note(title: "On the Usage of "Holomorphic" and "Analytic")[...] // 正确 — 内层改用单引号 #note(title: "On the Usage of 'Holomorphic' and 'Analytic'")[...] ``` #### 组件 name/title 参数中的数学公式 `name:` / `title:` 参数可以传字符串（`"..."`）或 content（`[...]`），两种形式都能正确渲染其中的 `$...$` 数学公式。模板已通过 `eval(name, mode: "markup")` 自动解析字符串中的 markup 语法。 ```typst // 两种写法都正确，数学正常渲染 #definition(name: "$L^p$ Space")[...] #definition(name: [$L^p$ Space])[...] // 推荐：字符串形式更简洁 #theorem(name: "Properties of $sin$ and $cos$")[...] ``` **注意**：使用字符串形式时，`$...$` 内的 Typst 数学符号必须正确（如 `!=` 而非 `neq`），否则 `eval` 解析时会报 `unknown variable` 错误。 #### 分数的分子/分母非单因子时必须加括号 `/` 只把紧邻的**单个因子**作为分子和分母。分母（或分子）含多字符结构或运算时必须加括号，否则解析错误。 **绝对值的特殊处理**：使用 `abs()` 函数形式后无需再加外层括号（`abs()` 自身作为一个完整因子）。但若使用 `|...|` 形式则必须加外层括号（见下方「绝对值用 abs(xxx)，不用 |xxx|」陷阱）： ```typst // 错误 — 分母只解析出单个因子，多字符结构被截断 $z^5 / |z|^4$ // 分母只取到 "|"，剩余 "z|^4" 并排在分数旁 $x + y / 2$ // 实际是 x 加上分数 y/2 // 正确 — abs() 形式（推荐，无需额外括号） $z^5 / abs(z)^4$ $z / abs(z)$ $x / abs(z)$ $abs(f(z)) / abs(g(z))$ // 正确 — 普通非单因子加括号 $(x + y) / 2$ // 想要 (x+y)/2 必须加括号 $z^5 / (w^4)$ // 含运算的幂次也加括号保险 ``` **判定规则**：分子/分母只要不是单个字母或数字（可带上下标，如 `x_i`、`z^2`），就必须加括号。**但 `abs(...)` 作为一个整体函数调用，可以视为单个因子**——这就是统一使用 `abs()` 形式的另一优势。 #### 绝对值用 abs(xxx)，不用 |xxx| Typst 数学模式中的 `|...|` **不会自动调整大小**，且在分式、根号、嵌套结构中容易被解析为独立竖线元素（见上文"分数的分子/分母非单因子时必须加括号"陷阱）。**统一使用函数形式 `abs(xxx)`**，自动缩放并避免歧义： ```typst // 错误 — |xxx| 不会自动缩放，且容易被误解为单字符 $|z - z_0|$ $|f(z)| / |g(z)|$ $root(n, |a_n|)$ // 正确 — abs() 自动缩放，且作为整体单元参与解析 $abs(z - z_0)$ $abs(f(z)) / abs(g(z))$ $root(n, abs(a_n))$ ``` **判定规则**：所有形如 `|表达式|` 的绝对值（含 `|z|`、`|c_n|`、`|z - z_0|`、`|f(z)|` 等）一律改写为 `abs(表达式)`，不论出现在正文公式、分式分子分母、根号内、积分限、求和限等任何位置。 **非绝对值的竖线严禁转换**：`|` 在数学模式中还有其他用途，批量替换前必须逐行分类排查（统计每行 `|` 个数，奇数行必然含非绝对值竖线）： | 用途 | 示例 | 处理 | |------|------|------| | 集合构建分隔符 | `{(x, y) \| x, y in bb(R)}` | 保留原样（本仓库写法为 `\|`） | | 整除符号 | `$q \| k_1 - k_2$`（q 整除 k₁−k₂） | 保留原样 | | 分隔符参数 | `delim: "\|"` | 保留原样 | **批量替换流程要求**：先全量统计含 `|` 的行并按奇偶分类 → 偶数行逐行配对转换（行内配对，禁止跨行正则）→ 奇数行逐行人工判定 → 转换后 grep 检查 `abs(` 内是否误含 ` in `、`\|` 等集合构建特征 → `typst compile` 验证退出码为 0。跨行正则（如 `\|([^|]+)\|` 直接作用于全文）会把不同行的孤立竖线错误配对，造成大面积损坏。 **积分/求和限中的集合描述例外**：形如 `integral_({|f| > M})` 的集合描述中的 `|f|` 表示集合定义中的属性条件，作为花括号集合构造语法的一部分，**保持原样不改**——这是集合描述的语法元素，不是绝对值表达式： ```typst // 保持原样 — 花括号内的集合描述语法 $integral_({|f| > M}) |f| dif mu$ // 集合 {|f| > M} 内的积分 // 但若此处出现了真正的绝对值计算且需要自动缩放，仍应改用 abs() $abs(f)$ ``` #### n 次方根用 root(n, x)，不用 sqrt 二参形式 `sqrt(x, n)` 的第二参数（根指数）不能是函数调用或含绝对值的表达式（如 `abs(a_n)`），会报 `unexpected argument`。统一改用 `root(指数, 被开方数)`： ```typst // 错误 — sqrt 第二参数不接受函数调用 $sqrt(n, abs(a_n))$ // 正确 — root(指数, 被开方数) $root(n, abs(a_n))$ $root(n, n)$ // n 次根号 n ``` #### 标点位置 独立数学公式的句号等标点必须写在数学环境内部： ```typst // 错误 $ G(a_n; x) = sum_(n=0)^oo a_n x^n $. // 正确 $ G(a_n; x) = sum_(n=0)^oo a_n x^n. $ ``` #### Display math 保持原样 如果原内容是 display math，不要擅自改写成行内数学。 #### 括号自动缩放 Typst 自动缩放普通括号，通常不需要 LaTeX 的 `\left`/`\right`。需要长竖线时使用 `lr(...)`。 #### `int` → `integral` 遗忘 LaTeX 习惯用 `\int`，Typst 必须写 `integral`。`int` 是未知变量，会报错。 ```typst // 错误 $int_0^1 f(x) dif x$ // 正确 $integral_0^1 f(x) dif x$ // 二重积分 $integral.double_S f dif S$ // 闭合曲面积分（无 oint 符号） $integral_(partial V) bold(E) dot dif bold(S)$ ``` #### `text()` 字符串参数 Typst 的 `text()` 函数必须传入字符串，未加引号的参数会被当作变量： ```typst // 错误 — "self" 被当作变量名 $U_(text(self))$ // 正确 $U_(text("self"))$ ``` #### `sim`/`cdot` 等 LaTeX 宏不存在 Typst 数学模式不识别 `\sim`、`\cdot` 等 LaTeX 宏名。使用原生操作符： | 意图 | 错误写法 | 正确写法 | |------|---------|---------| | 约等于/相似 | `$a sim b$` | `$a ~ b$` 或 `$a approx b$` | | 点乘 | `$a cdot b$` | `$a dot b$` | | 趋向 | `$x to oo$` | `$x arrow oo$` 或 `$x -> oo$` | **占位符场景**同样报 `unknown variable: cdot`： ```typst // 错误 — cdot 作为绝对值/范数中间的占位符也是未知变量 $abs(cdot)$ // 可行 — 用 dot 充当占位符 $abs(dot)$ // 更推荐 — 在正文中改用自然语言描述（如 "the complex modulus"），避免占位符 ``` #### `ll`, `gg` 等比较符号不存在 Typst 数学模式不识别 `\ll`、`\gg` 等 LaTeX 宏名。使用原生比较操作符： | 意图 | 错误写法 | 正确写法 | |------|---------|---------| | 远小于 | `$d \ll \sqrt(A)$` | `$d << \sqrt(A)$` | | 远大于 | `$a \gg b$` | `$a >> b$` | #### `laplacian`, `oint` 等非标准符号不存在 Typst 数学模式不识别 `\laplacian`、`\oint` 等 LaTeX 宏名。使用等价表达： | 意图 | 错误写法 | 正确写法 | |------|---------|---------| | 拉普拉斯算子 | `$\laplacian V = 0$` | `$nabla^2 V = 0$` | | 闭合环路线积分 | `$\oint_sigma bold(f) dot d bold(l)$` | `$integral.cont_sigma bold(f) dot d bold(l)$` | | 闭合曲面积分 | `$\oint_sigma dif a$` | `$integral_(partial sigma) dif a$` 或 `$integral_sigma dif a$` | #### `const` 等多字母标识符未加引号 在数学模式中使用 `text()` 包裹的文本参数必须加引号，否则被当作未定义变量： | 意图 | 错误写法 | 正确写法 | |------|---------|---------| | 常数符号 | `$sigma approx frac(const, R_c)$` | `$sigma approx frac("const", R_c)$` | | 文本标签 | `$V_(text(self))$` | `$V_(text("self"))$` | #### 未知符号查阅官网 遇到不确定的数学符号时，查阅 Typst 官方符号文档： https://typst.app/docs/reference/symbols/sym/ 常见需要查阅的情况： - `\laplacian` 等非标准 LaTeX 宏 — Typst 不支持，需用等价表达 - `\ll`、`\gg`、`\lll` 等罕见比较符号 — 可用 `<<`、`>>`、`<<<` 替代 - `\hbar`、`\ell` 等物理/数学特殊符号 — 查阅官网确认可用名称 #### `infty` → `oo` 无限大符号是 `oo`（两个字母 o），不是 `infty` 也不是 `infinity`： ```typst // 错误 $n -> infinity$ // 正确 $n -> oo$ ``` #### `cases()` 不用 `&` 对齐，逗号是分行符 Typst 的 `cases()` 函数中，**逗号是分行符**（等价于换行），同一行内的多列用**空格**分隔。不能使用 LaTeX 风格的 `&` 对齐语法。 ```typst // 错误 — LaTeX \begin{cases} 的 & 对齐语法 $ cases( Delta u = 0, & text("in ") Omega, u = g, & text("on ") partial Omega, ) $ // 错误 — 逗号是分行符，会把表达式和条件拆成两行 $ cases( Delta u = 0, text("in ") Omega, u = g, text("on ") partial Omega, ) $ // 正确 — 同行内用空格分隔列，逗号只在行末用于换行 $ cases( Delta u = 0 text("in ") Omega, u = g text("on ") partial Omega, ) $ ``` --- ## 4. 标签与交叉引用 ### 标签命名规范 | 类型 | 前缀 | 示例 | |------|------|------| | 图片 | `fig:` | `` | | 定理 | `thm:` | `` | | 定义 | `def:` | `` | | 章节 | `sec:` | `` | ### 引用方式 - 图片引用：`@fig:example` - 自定义组件引用：`#link(