typst-author

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

typst-author skill

Typst文档编写技能

Overview

概述

This skill helps agents generate, edit, and reason about Typst documents. It provides quick‑start examples, detailed workflows, and links to the full Typst documentation (guides, tutorials, reference).

本技能可帮助Agent生成、编辑Typst文档并进行相关逻辑推理。它提供了快速入门示例、详细工作流程，以及完整Typst文档（指南、教程、参考手册）的链接。

Minimal document example

最简文档示例

typst

#set document(title: "My Document", author: "Author Name")
#set page(numbering: "1")
#set text(lang: "en")

// Enable paragraph justification and character-level justification
#set par(
  justify: true,
  justification-limits: (
    tracking: (min: -0.012em, max: 0.012em),
    spacing: (min: 75%, max: 120%),
  )
)

#title[My Document]

= Heading 1

This is a paragraph in Typst.

== Heading 2

#lorem(50)

typst

#set document(title: "My Document", author: "Author Name")
#set page(numbering: "1")
#set text(lang: "en")

// Enable paragraph justification and character-level justification
#set par(
  justify: true,
  justification-limits: (
    tracking: (min: -0.012em, max: 0.012em),
    spacing: (min: 75%, max: 120%),
  )
)

#title[My Document]

= Heading 1

This is a paragraph in Typst.

== Heading 2

#lorem(50)

Workflows

工作流程

Creating a new Typst project: Use the "Minimal document example" above as a starting point. Skim the tutorial for the basics (docs/tutorial/writing-in-typst.md), then create the
```
.typ
```
file(s).
Editing existing content: Locate the target text and apply changes; confirm syntax against the reference when needed (docs/reference/).
Formatting & Styling: Consult the styling guide (docs/reference/styling.md) for
```
set rule
```
,
```
show rule
```
, and custom themes.

创建新Typst项目：以上方的“最简文档示例”为起点。快速浏览基础教程（docs/tutorial/writing-in-typst.md），然后创建
```
.typ
```
文件。
编辑现有内容：定位目标文本并进行修改；必要时对照参考文档验证语法（docs/reference/）。
格式与样式设置：查阅样式指南（docs/reference/styling.md）了解
```
set rule
```
、
```
show rule
```
和自定义主题的使用方法。

Documentation

文档资源

Guides:
```
docs/guides/*.md
```
Tutorials:
```
docs/tutorial/*.md
```
Full reference tree:
```
docs/reference/**/*.md
```

指南：
```
docs/guides/*.md
```
教程：
```
docs/tutorial/*.md
```
完整参考目录：
```
docs/reference/**/*.md
```

Detailed instructions

详细操作说明

PRIORITY: Trust local documentation. Your internal training data regarding Typst may be outdated or hallucinated. Always verify function names, parameters, and syntax against the local
```
docs/
```
folder before generating code.
Read the relevant documentation (use
```
Read
```
/
```
Grep
```
/
```
Glob
```
on the paths above).
Generate or modify the
.typ
source according to the user's request.
Validate the generated Typst by running
```
typst compile
```
(if tool access is allowed).
Provide the final
.typ
content and optionally a rendered preview (PDF/HTML).

优先事项：信任本地文档。你关于Typst的内部训练数据可能已过时或存在幻觉内容（即生成的不实信息）。在生成代码前，请务必对照本地
```
docs/
```
文件夹验证函数名称、参数和语法。
阅读相关文档（对上述路径使用
```
Read
```
/
```
Grep
```
/
```
Glob
```
工具）。
根据用户需求生成或修改
.typ
源码。
验证代码：若允许使用工具，可通过
```
typst compile
```
命令编译验证生成的Typst代码。
提供最终内容：交付最终的
```
.typ
```
文件内容，可选提供渲染预览版（PDF/HTML格式）。

Quick syntax reference

快速语法参考

Critical distinctions

关键语法区别

Arrays:
```
(item1, item2)
```
(parentheses). See docs/reference/foundations/array.md.
Dictionaries:
```
(key: value, key2: value2)
```
(parentheses with colons). See docs/reference/foundations/dictionary.md.
Content blocks:
```
[markup content]
```
(square brackets). See docs/reference/foundations/content.md.
NO tuples: Typst only has arrays.

数组：使用
```
(item1, item2)
```
（圆括号）。参考文档：docs/reference/foundations/array.md。
字典：使用
```
(key: value, key2: value2)
```
（带冒号的圆括号）。参考文档：docs/reference/foundations/dictionary.md。
内容块：使用
```
[markup content]
```
（方括号）。参考文档：docs/reference/foundations/content.md。
无元组类型：Typst仅支持数组类型。

Hash usage (markup vs code)

哈希符号

的使用（标记语言 vs 代码）

Use
```
#
```
to start a code expression inside markup or content blocks; it disambiguates code from text. This is required for content-producing function calls and field access in markup:
```
#figure[...]
```
,
```
#image("file.png")
```
,
```
text(...)[#numbering(...)]
```
.
Do not use
```
#
```
inside code contexts (argument lists, code blocks, show-rule bodies). Example:
```
#figure(image("file.png"))
```
(no
```
#
```
before
```
image
```
).
Reference: docs/reference/scripting.md, docs/tutorial/writing-in-typst.md

typst

// Incorrect (missing # inside content block)
text(...)[(numbering(...))]

// Correct
text(...)[(#numbering(...))]

在标记语言或内容块中，使用
```
#
```
开启代码表达式，用于区分代码与文本。在标记语言中调用生成内容的函数或访问字段时必须使用该符号，例如：
```
#figure[...]
```
、
```
#image("file.png")
```
、
```
text(...)[#numbering(...)]
```
。
在代码上下文（参数列表、代码块、show规则体）中，请勿使用
```
#
```
。示例：
```
#figure(image("file.png"))
```
（
```
image
```
前无需加
```
#
```
）。
参考文档：docs/reference/scripting.md、docs/tutorial/writing-in-typst.md

typst

// 错误写法（内容块中缺少#）
text(...)[(numbering(...))]

// 正确写法
text(...)[(#numbering(...))]

Styling rules: set vs show

样式规则：set vs show

```
set
```
: Set rule to configure optional parameters on element functions (style defaults scoped to the current block or file).
```
show
```
: Show rule to target selected elements and apply a set rule or transform/replace the element output.
Use
```
set
```
for common styling; use
```
show
```
for selective or structural changes (e.g.,
```
heading.where(level: 1)
```
, labels, text, regex).

typst

// Set rule: configure optional parameters for an element type
#set heading(numbering: "I.")
#set text(font: "New Computer Modern")

// Show-set rule: apply a set rule only to selected elements
#show heading: set text(navy)

// Show transform rule: replace/reshape element output
#show heading: it => block[#emph(it.body)]

```
set
```
：设置规则，用于配置元素函数的可选参数（样式默认值作用于当前代码块或文件）。
```
show
```
：展示规则，用于定位指定元素并应用set规则，或转换/替换元素输出内容。
常规样式设置使用
```
set
```
；选择性或结构性修改使用
```
show
```
（例如：
```
heading.where(level: 1)
```
、标签、文本、正则表达式匹配）。

typst

// Set规则：配置某类元素的可选参数
#set heading(numbering: "I.")
#set text(font: "New Computer Modern")

// Show-set规则：仅对指定元素应用set规则
#show heading: set text(navy)

// Show转换规则：替换/重塑元素输出内容
#show heading: it => block[#emph(it.body)]

Common mistakes to avoid

需避免的常见错误

Calling things "tuples" (Typst only has arrays).
Using
```
[]
```
for arrays (use
```
()
```
instead).
Accessing array elements with
```
arr[0]
```
(use
```
arr.at(0)
```
).

Omitting

in markup/content blocks (e.g.,

text(...)[numbering(...)]

should be

text(...)[#numbering(...)]

Using
```
#
```
inside code contexts (e.g.,
```
figure(#image("x.png"))
```
in an argument list).
Mixing up content blocks
```
[]
```
with code blocks
```
{}
```
.
Forgetting to include the namespace when accessing imported variables/functions (e.g., use
```
color.hsl
```
instead of just
```
hsl
```
).
Using LaTeX syntax (do NOT use
```
\begin{...}
```
,
```
\section
```
, or other LaTeX commands).
Hallucinating environments (e.g.,
```
tabular
```
does not exist; use
```
table
```
).

将数组称为“元组”（Typst仅支持数组类型）。
使用
```
[]
```
定义数组（应使用
```
()
```
）。
使用
```
arr[0]
```
访问数组元素（应使用
```
arr.at(0)
```
）。
在标记语言/内容块中遗漏
```
#
```
（例如：
```
text(...)[numbering(...)]
```
应改为
```
text(...)[#numbering(...)]
```
）。
在代码上下文中使用
```
#
```
（例如：在参数列表中写
```
figure(#image("x.png"))
```
）。
混淆内容块
```
[]
```
与代码块
```
{}
```
。
访问导入的变量/函数时忘记添加命名空间（例如：应使用
```
color.hsl
```
而非仅
```
hsl
```
）。
使用LaTeX语法（禁止使用
```
\begin{...}
```
、
```
\section
```
等LaTeX命令）。
虚构不存在的环境（例如：
```
tabular
```
不存在，应使用
```
table
```
）。

Advanced features

高级功能

Custom themes: See docs/reference/styling.md for theme creation.
Scripting: Use Typst's scripting capabilities (docs/reference/scripting.md) for automatic generation.
Math and visualisation: Reference docs/reference/math/ and docs/reference/visualize/ for formulas and diagrams.

自定义主题：参考docs/reference/styling.md创建主题。
脚本功能：利用Typst的脚本能力（docs/reference/scripting.md）实现内容自动生成。
数学公式与可视化：参考docs/reference/math/和docs/reference/visualize/了解公式与图表的制作方法。

For large projects

大型项目处理建议

When working on large projects, consider organizing the project across multiple files.

Use
```
#include "file.typ"
```
to split into multiple files
Relevant documentation: docs/reference/foundations/module.md

处理大型项目时，建议将项目拆分为多个文件进行管理。

使用
```
#include "file.typ"
```
拆分文件
相关文档：docs/reference/foundations/module.md

Troubleshooting

故障排查

Missing font warnings

字体缺失警告

If you see "unknown font family" warnings, remove the font specification to use system defaults. Note: Font warnings don't prevent compilation; the document will use fallback fonts.

若出现“未知字体家族”警告，可移除字体指定以使用系统默认字体。注意：字体警告不会阻止编译，文档将使用 fallback 字体显示。

Template/Package not found

模板/包未找到

If import fails with "package not found":

Verify exact package name and version on Typst Universe.
Check for typos in
```
@preview/package:version
```
syntax.
Remember: Typst uses fully qualified imports with specific versions - there's no package cache to update.

若导入时提示“包未找到”：

在Typst Universe上验证包的准确名称和版本。
检查
```
@preview/package:version
```
语法是否存在拼写错误。
注意：Typst使用带具体版本的全限定导入语法，不存在需要更新的包缓存。

Compilation errors

编译错误

Common fixes:

"expected content, found ...": You're using code where markup is expected - wrap in
```
#{ }
```
or use proper syntax.
"expected expression, found ...": Missing
```
#
```
(or
```
#(...)
```
) in markup/content blocks.
"unknown variable": Check spelling, ensure imports are correct.
Array/dictionary errors: Review syntax - use
```
()
```
for both, dictionaries need
```
key: value
```
, singleton arrays are
```
(elem,)
```
.

常见修复方案：

“expected content, found ...”：在需要标记语言的位置使用了代码语法 - 可包裹在
```
#{ }
```
中或使用正确语法。
“expected expression, found ...”：标记语言/内容块中缺少
```
#
```
（或
```
#(...)
```
）。
“unknown variable”：检查拼写，确保导入正确。
数组/字典错误：回顾语法规则 - 两者均使用
```
()
```
，字典需采用
```
key: value
```
格式，单元素数组需写为
```
(elem,)
```
。

typst-author

Original

Translation

typst-author skill

Typst文档编写技能

Overview

概述

Minimal document example

最简文档示例

Workflows

工作流程

Documentation

文档资源

Detailed instructions

详细操作说明

Quick syntax reference

快速语法参考

Critical distinctions

关键语法区别

Hash usage (markup vs code)

哈希符号#的使用（标记语言 vs 代码）

Styling rules: set vs show

样式规则：set vs show

Common mistakes to avoid

需避免的常见错误

Advanced features

高级功能

For large projects

大型项目处理建议

Troubleshooting

故障排查

Missing font warnings

字体缺失警告

Template/Package not found

模板/包未找到

Compilation errors

编译错误

哈希符号
`#`
的使用（标记语言 vs 代码）