| name | typst-writing-conventions |
| description | 当编辑/创建 .typ 文件时，必须使用本技能以确保符合 Typst 语法规范（如 subset→subset.eq, \sigma→sigma, integral→integral 等）、符号映射规则、文档层级结构和写作风格约定。尤其适用于新增数学公式较多的笔记时。 |
| user_invocable | false |
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 自动缩放方括号 |
硬规则（必须遵守）
- 不属于符号：写
$in.not$，不要写 $notin$
- 子集：统一写
$subset$
- 箭头：
$->$、$<=>$，不保留 LaTeX 宏名
- 不等于：
$!=$（注意空格：$!= $ 或 $a != b$）
- 函数复合：
$compose$
- 微分符号：使用正体
dif x、dif t
- 导数点记号：
dot(x)、dot.double(x)、dot.triple(x)
- 积分号：用
integral，不是 int。二重/三重：integral.double、integral.triple
text() 必须用字符串参数：写 text("something")，不是 text(something)- 点乘：写
a dot b，不用 a cdot b（cdot 不存在）
\left(/\right) 不存在：Typst 自动缩放括号，不需要 \left/\right
常见陷阱
裸下标问题
Typst 不支持 $_x$，下标 _ 前必须有主体。
// 错误
$_x$
// 正确：空主体下标
$""_x$
多字母变量问题
Typst 将连续字母识别为内置函数名（如 sin、exp），导致编译错误。
// 正体多字母变量：用引号包裹
$"ext"$, $"const"$, $"max"$
// 斜体多字母变量：用空格分开
$e x t$
// 示例
$bold(F)_i^("ext")$ // 外力
标点位置
独立数学公式的句号等标点必须写在数学环境内部：
// 错误
$
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 是未知变量，会报错。
// 错误
$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() 函数必须传入字符串，未加引号的参数会被当作变量：
// 错误 — "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$ |
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：
// 错误
$n -> infinity$
// 正确
$n -> oo$
4. 标签与交叉引用
标签命名规范
| 类型 | 前缀 | 示例 |
|---|
| 图片 | fig: | <fig:example> |
| 定理 | thm: | <thm:mvt> |
| 定义 | def: | <def:continuous> |
| 章节 | sec: | <sec:intro> |
引用方式
- 图片引用：
@fig:example
- 自定义组件引用：
#link(<label>)[显示文本]
#definition(name: "Continuous Function")[
A function $f: X -> Y$ is continuous if...
] <def:continuous>
Later, we refer to *#link(<def:continuous>)[Continuous Function]*.
5. 图片
#figure(
image("img/example.png", width: 60%),
caption: [This is an example figure.],
placement: auto,
supplement: [Fig.]
) <fig:example>
6. 表格
重要规则
表格单元格中如果包含数学公式，必须使用中括号 [...] 包裹，不能使用引号 "..."。
// 正确：数学公式用中括号
#tex-table(
("Translational", "Rotational"),
([Position $x$], [Angle $theta$]),
([Velocity $v = dot(x)$], [Angular velocity $omega = dot(theta)$]),
)
// 错误：引号内数学公式不会渲染
#tex-table(
("Translational", "Rotational"),
("Position $x$", "Angle $theta$"),
)
纯文本单元格可以使用引号。
7. 文献引用
- 正文引用：
@citation_key
- 脚注：
#footnote[...]
- 参考文献列表放在文件末尾：
#bibliography("references.bib")
8. 公式编号
默认公式不编号。需要编号时使用模板提供的 #eq() 包装器：
#eq[$
E = m c^2
$]
编号格式为 (章号.公式序号)，如 (1.1)。
8.5 收敛箭头（xarrow 包）
使用 @preview/xarrow:0.4.0 包实现带标注的收敛箭头：
#import "@preview/xarrow:0.4.0": xarrow
// 几乎处处收敛
$f_n xarrow("a.e.") f$
// 依测度收敛
$f_n xarrow(mu) f$
// 几乎一致收敛
$f_n xarrow("a.u.") f$
// L^p 范数收敛
$f_n xarrow(L^p) f$
8.6 积分记号惯例
// 基本积分
$integral_X f dif mu$
// 集合上的积分
$integral_A f dif mu$
$integral_(E_n) f dif mu$
// 集合描述作为积分下标（注意花括号）
$integral_({|f| > M}) |f| dif mu$
$integral_({x in X : f(x) >= epsilon}) f dif mu$
// 上确界/下确界带下标
$sup_(s <= f) integral_X s dif mu$
$liminf_(n->oo) integral_X f_n dif mu$
9. 写作风格规范
内容职责原则（SRP）
每个笔记文件/章节只负责自己领域的内容，不重复其他笔记已有的定义和定理：
- 不要重复定义：如果某个概念（如 Riemann 积分的定义）已在其他笔记中给出（如《Analyse Mathématique》），本笔记只需简要提及并引用，不要重新定义
- 不要重复定理：如果某个定理（如 Lebesgue 判据）已在另一门课的笔记中证明过，这里只需陈述结论并注明出处，或用
#note 提示读者参阅
- 聚焦本章视角：同一个定理在不同笔记中出现时，应从本章的视角重新阐述其意义，而非照搬原始证明
- 交叉引用优先：用
#link 或正文说明指向已有内容，避免信息冗余
示例：在实分析笔记的"与 Riemann 积分的关系"一节中：
- ✗ 重新定义 Riemann 积分（数学分析笔记已有）
- ✗ 重新证明 Lebesgue 判据（数学分析笔记已有）
- ✓ 直接陈述 Lebesgue 判据的结论，注明"此定理的证明见数学分析笔记"
- ✓ 聚焦于 Riemann 可积与 Lebesgue 可积的关系、反常积分的对比等本章独有内容
语言与术语
- 正文使用英文，正文中不得出现中文（包括中文括号内的翻译、中文术语、中文解释）
- 中文仅能出现在
// 注释中：== Section Title // 中文标题
- 组件
name 参数使用英文
- 数学术语使用学科通用英文表述
证明写作
- 证明步骤之间用空行分隔，保持逻辑段落清晰
- 长证明使用
*Step N*: 标记关键步骤
- 证明结束由
#proof 组件自动添加 ■ 符号，不需要手动写 QED
内容组织模式
典型的定理/定律展开模式（按需选用）：
#theorem / #law(name: "...")[...]
#proof[...]
#corollary[...] // 直接推论
#example[...] // 说明性例子或反例
#note[...] // 对比、适用条件说明
- 物理定律用
#law，数学定理用 #theorem
#proof 可用于两者之后
组件选择指南
组件不能滥用。参考项目现有内容的分工：
| 组件 | 用途 | 何时使用 | 何时不用 |
|---|
#definition | 定义核心概念 | 引入新术语/新量时（电场强度、电流密度、通量） | 仅仅是列举属性或计算步骤时不用 |
#law | 物理定律（实验或简单推理得出） | 库仑定律、欧姆定律、焦耳定律、基尔霍夫定律、安培定律 | 纯数学定理不用 |
#theorem | 数学定理或推论（经严格证明的命题） | 唯一性定理、叠加原理、矢势的泊松方程 | 物理定律不用 |
#property | 一组相关性质的枚举 | 只有确实在列举一组属性时用（如"电力线的性质"） | 单一公式、单一解释、计算过程不用 |
#example | 带计算的工作示例 | 演示定律的应用、对称性计算 | 纯文字说明不用 |
#note | 补充说明、对比、洞察 | 概念对比、适用条件、与其他定理的关系 | 核心内容不应放进 note |
#proof | 定理或定律的推导证明 | 紧跟在 #theorem / #law 之后 | 没有明确陈述时不用单独使用 |
#caution | 易错点或警告 | 需要强调不能忽略的条件 | 日常说明不用 |
两个常见误区：
- 不要把
#property 当作"包装任何非定理内容"的万能工具 — 很多内容直接写成普通段落即可
- 不是每个概念都需要用组件包裹：SI 单位说明、常数值、过渡段、列表列举等，直接写纯文本
参考写法对比：
// ✓ 正确：核心定义用 #definition
#definition(name: "Current Density")[
The *current density* $bold(J)$ is defined as $bold(J) = n q bold(v)$.
]
// ✓ 正确：过渡段直接写纯文本
The SI unit of the electric field is newtons per coulomb ($"N/C"$).
// ✓ 正确：分类列举直接写列表（不用 #property）
- *Volume current density* $bold(J)$
- *Surface current density* $bold(K)$
- *Line current* $I$
// ✓ 正确：property 只用于确实在列举属性时
#property(name: "Properties of Electric Field Lines")[
- They originate from positive charges and terminate on negative charges.
- They never cross each other.
]
// ✗ 错误：将 #property 当作通用包装器
#property(name: "Joule Heating")[ // ← 不应使用 property
The power density is $p = bold(J) dot bold(E)$.
]
// 应改为：
#law(name: "Joule Heating")[ // ← 物理定律用 law
The power density is $p = bold(J) dot bold(E)$.
]
// 或者直接写纯文本段落：
The power dissipated per unit volume is $p = bold(J) dot bold(E)$.
注释的使用场景
#note：概念对比、适用条件说明、与其他定理的关系#caution：容易出错的地方、条件不能省略的警告#example：反例（说明条件不可去掉）、典型应用
集合与函数空间记号
- 集合描述：
${x in X : P(x)}$（使用冒号 : 而非竖线）
- $L^p$ 空间：
$L^1 (X, mu)$（空格分隔参数）
- 特征函数/指示函数：
$chi_A$ 或 $chi_(A)$
- 几乎处处：正文中写
a.e.，公式中写 "a.e."
积分记号
- 积分微元使用正体：
$integral_X f dif mu$
- 积分区域用下标：
$integral_A f dif mu$、$integral_(E_n) f dif mu$
- 集合上的积分限制：
$integral_({|f| > M}) |f| dif mu$（注意花括号内的集合描述）
10. 强约束清单
- 所有数学公式使用正确的 Typst 语法，不保留 LaTeX 宏
- 多字母变量必须用引号包裹或空格分开
- 下标前必须有主体
- Display math 标点写在环境内部
- 不改动模板公共接口名称
- 保持与现有内容的风格一致性
- 补全后确保文件可编译（使用
typst compile 验证）
- 正文中不得出现中文（中文仅限
// 注释和 == Title // 中文标题 格式）
- 不删除或修改已有内容，除非明确要求
- 正文中的过渡段落（连接定理之间的逻辑）直接写为普通文本，不使用组件包裹
