typst-writer

Typst Writer

此技能为编写正确的 Typst 代码提供指导，重点在于避免因将 Typst 与其他语言混为一谈而导致的常见语法错误。

核心原则

1. 切勿假定其他语言的语法也适用——Typst 有自己的语义，尤其是在数据结构方面
2. 核实不确定的语法——不确定时，请查阅官方文档
3. 使用惯用模式——遵循 Typst 惯例，编写整洁、易维护的代码

快速语法参考

重要区别：

• 数组：(item1, item2)——圆括号
• 字典：(key: value, key2: value2)——带冒号的圆括号
• 内容块：[markup content]——方括号
• 没有元组——Typst 只有数组

详细语法规则和常见模式，请参阅 references/syntax.md。

文档资源

官方文档

• 核心语言参考：https://typst.app/docs/reference/
• Typst Universe——中央软件包和模板注册表：
  • 主页（JS SPA）：https://typst.app/universe
  • 整个注册表就是一个普通的 GitHub 仓库：https://github.com/typst/packages

搜索 Typst 软件包

Typst Universe（官方软件包注册表）没有编程接口，但你可以通过 GitHub 搜索软件包：

• 大多数软件包托管在 GitHub 上
• 使用 gh search 或 SearXNG 的仓库搜索（请参阅 searxng-search Skill）
• 示例：在仓库中搜索“typst diagram”或“typst table”

使用 GitHub CLI

GitHub 直接搜索示例：

# Search for typst repos about some topic
gh search repos --language "typst" --json "url,language,description" diagram arrows ... 

# List all files in a given repo
gh search code --repo "Jollywatt/typst-fletcher"

# In a repo, search through all files of some type
gh search code --repo "Jollywatt/typst-fletcher" --extension "md" arrow node ...

何时查阅文档

• 不确定函数签名或参数
• 需要核实较少见功能的语法
• 查找内置函数或方法
• 探索可用的软件包（例如，用于绘图的 fletcher、用于页边注的 drafting、用于高级表格的 tablex）

必要时使用 WebFetch 获取最新文档进行核实。

工作流

1. 编写前：如果语法不明确，请查阅 references/syntax.md 或相关文档
2. 编写时：
   • 使用正确的数据结构语法（数组用 ()，内容用 []）
   • 使用 #let name(params) = { ... } 定义函数
   • 访问状态时使用 context 块
3. 编写后：检查是否混入了 Python 或其他语言的语法

应避免的常见错误

• ❌ 将内容称为“元组”（Typst 只有数组）
• ❌ 使用 [] 表示数组（应使用 ()）
• ❌ 使用 arr[0] 访问数组元素（应使用 arr.at(0)）
• ❌ 在标记上下文中忘记代码前缀 #
• ❌ 混淆内容块 [] 与代码块 {}

工作流示例

// Define custom functions for document elements
#let important(body) = {
  box(
    fill: red.lighten(80%),
    stroke: red + 1pt,
    inset: 8pt,
    body
  )
}

// Use state for counters
#let example-counter = state("examples", 1)

#let example(body) = context {
  let num = example-counter.get()
  important[Example #num: #body]
  example-counter.update(x => x + 1)
}

// Arrays for data
#let factions = (
  (name: "Merchants", color: blue),
  (name: "Artisans", color: green)
)

// Iterate and render
#for faction in factions [
  - #text(fill: faction.color, faction.name)
]

编码指南

避免混合内容与布局

应使用 #set、#show 和自定义函数，避免将内容与布局指令混在一起；更重要的是，这能确保整个文档的视觉风格一致。

尽量简洁并依赖默认值

Typst 函数通常为布局参数提供合理的默认值。如果不确定某个参数应该取什么值，就不指定它。

同样，许多函数参数允许根据用户希望对布局进行的控制程度而采用不同类型。例如：

#table(
  columns: 3,
  ...
)

和

#table(
  columns: (auto, auto, auto),
  ...
)

效果完全相同。如果不需要对某一列的尺寸进行更精细的控制，优先使用第一种写法。

有可用的标记快捷写法时优先使用

使用 to-emphasize，而不是 #emph[to-emphasize]。

优先使用 Unicode 字面量，而非表达式

例如，直接写 π，而不是 $pi$ 或 #sym.pi；直接写 🧮，而不是 #emoji.abacus。

读取 Typst 文件中的内容

除了编译之外，typst CLI 命令还可以使用 typst query 查询 Typst 文件，使用 Typst 选择器，并以 JSON 格式获取结果。

例如，typst query the_document.typ "heading.where(level: 1)" | jq ".[].body.text" 会列出文档中所有一级章节标题。遗憾的是，它不会告诉你这些标题在文件中的确切位置，不过 Typst 文件很容易用 grep 搜索。

有关更多信息，请参阅关于 query 的在线文档。

包的使用

需要专用功能时：

1. 在 https://typst.app/universe/ 搜索包
2. 使用 #import "@preview/package:version" 导入
3. 查阅包文档了解 API

热门包：

• drafting：为进行中的文档添加注释和评论
• gentle-clues：添加提示框、提示、备注和告诫
• showybox：通用、可自定义的文本框，带有标题和页脚。例如，可用于定义、定理或突出显示重要段落
• itemize：为项目列表、枚举、检查清单、树形列表等提供美观的布局
• cetz：通用图表和绘图，可显式指定位置（坐标），是大多数 Typst 绘图库的基础
• fletcher：图表、流程图、自动机、树等，支持自动布局
• chronos：时序图
• timeliney：甘特图
• herodot：线性时间线
• lilaq：数据可视化和绘图
• tablem：以类似 Markdown 表格的格式编写表格，可轻松控制线条、合并单元格等
• cmarker：将 Markdown（内嵌内容或独立文件）渲染为 Typst 文档的一部分
• polylux：演示文稿、幻灯片
• suiji：在 Typst 代码中生成随机数
• zebraw：代码列表，支持行号、高亮行、内嵌 Typst 注释/说明等
• lovelace：算法/伪代码
• conchord：歌词，支持叠加和弦变化、吉他和弦图和六线谱
• eqalc：将数学公式转换为可调用的 Typst 函数
• jlyfish：将 Typst 用作 Julia 笔记本：在 Typst 中嵌入 Julia 代码以生成内容、可视化等
• pyrunner：在 Typst 中嵌入并调用非 I/O Python 代码

使用模板

Typst Universe 提供许多预先构建的模板，可用于报告、论文、简历、演示文稿等。模板提供完整的文档样式和结构。

查找模板

• 浏览模板：https://typst.app/universe/search/?kind=templates
• 按类别筛选：报告、论文、学位论文、简历等
• 查看模板文档，了解参数和示例

使用模板

1. 导入模板：#import "@preview/template-name:version": *
2. 使用 #show: template-name.with(param: value, ...) 应用模板
3. 查阅模板文档，了解必需和可选参数

示例：

#import "@preview/bubble:0.2.2": bubble

// Some templates (like bubble) don't use the standard metadata set by `#set document(...)` (for now?),
// so we factor it out:
#let doc-md = (
  title: [My report],
  author: "Claude",
  date: datetime(year: 2025, month: 12, day: 8) // ALWAYS include explicit date in code (so we don't default to date of PDF build)
)

#set document(..doc-md)

#show: bubble.with(
  ..doc-md,
  date: doc-md.date.display("[day]-[month]-[year]"), // some templates want a string here, not a `datetime` object, so we override date here
  subtitle: "A detailed analysis",
  affiliation: "Your Organization",
  main-color: rgb("#FF6B35"),
  color-words: ("important", "key", "critical"),
)

// Your content follows
= Introduction
...

与包的主要区别：

• 模板通常通过一个“主”函数使用 #show: 为整个文档应用样式
• 包提供可显式调用的函数/组件
• 模板通常内置标题页和文档结构

热门模板：charged-ieee（IEEE 论文）、bubble（彩色报告）、modern-cv（简历）

参考文献和引用

Typst 支持使用 BibTeX（.bib）或 Hayagriva（.yml）格式文件管理引用和参考文献。

请参阅 references/bibliography.md

尽可能在参考文献文件中始终提供正确的 URL。

只要相关，就务必在文本中加入 @ref-name 引用。参考文献整理得再好，不引用也毫无用处。

完整文档结构模式

以下是学术论文的示例。 你需要撰写的大多数报告不必如此正式，但这算是一个典型示例。

“手动”布局（如有需要，例如用户提出了具体的布局要求）

#set document(
  title: "Document Title",
  author: "Your Name",
  date: auto,
)

#set page(
  paper: "a4",
  margin: (x: 2.5cm, y: 2.5cm),
  numbering: "1",
)

#set text(size: 11pt)
#set par(justify: true)
#set heading(numbering: "1.")

// Title page
#align(center)[
  #text(size: 24pt, weight: "bold")[Document Title]

  #v(1cm)
  #text(size: 14pt)[Your Name]

  #v(0.5cm)
  #datetime.today().display()
]

#pagebreak()

// Table of contents
#outline(title: "Table of Contents", indent: auto)

#pagebreak()

// Main content
= Introduction
Your introduction text...

= Methods
...

= Results
...

= Conclusion
...

#pagebreak()

// Bibliography
#bibliography("refs.bib", title: "References", style: "ieee")

使用模板（更简单）

#import "@preview/charged-ieee:0.1.4": *

#show: ieee.with(
  title: "Your Paper Title",
  authors: (
    (name: "Author One", email: "[email protected]"),
    (name: "Author Two", email: "[email protected]"),
  ),
  abstract: [
    Your abstract text here...
  ],
  index-terms: ("keyword1", "keyword2", "keyword3"),
  bibliography: bibliography("refs.bib"), // the ieee template takes care of bibliography itself. That's not always the case
)

// Content starts immediately
= Introduction
Your introduction text...

= Methods
...

= Results
...

= Conclusion
...

故障排除

缺少字体警告

如果看到“unknown font family”警告，请移除字体设置，改用系统默认字体

注意：字体警告不会阻止编译；文档会使用备用字体

未找到模板／包

如果导入时出现“package not found”：

• 在 Typst Universe 上核实准确的包名和版本
• 检查 @preview/package:version 语法中是否有拼写错误
• 确保网络连接正常（首次使用时会下载包）
• 请记住：Typst 使用带特定版本的完全限定导入，不存在可更新的包缓存

编译错误

常见修复方法：

• “expected content, found ...”：你在需要标记语法的地方使用了代码——请用 #{ } 包裹，或使用正确的语法
• “expected expression, found ...”：在标记语法上下文中缺少 # 前缀
• “unknown variable”：检查拼写，确保导入正确
• 数组／字典错误：检查语法——两者都使用 ()，字典需要 key: value，单元素数组写作 (elem,)

性能问题

对于大型文档：

• 使用 #include "file.typ" 将文档拆分为多个文件
• 编译特定页面：typst compile doc.typ output.pdf --pages 1-5
• 对编译过程进行性能分析（实验性）：typst compile --timings doc.typ