Typst 格式示例 — ClapEcho233

这篇文章整篇由 Typst 写成，与 Markdown 格式示例使用同一组例子。前半篇逐项对照标题、文字、列表、代码、表格、图片、脚注和公式，后半篇展示 Typst 的内容函数与布局。

源文件在 src/content/article/typst-guide/index.typ。本站通过 Pandoc 把 Typst 转成 HTML，再使用网页的字体与样式；下面的例子都以这条转换路径为准。

标题与文章信息

开头导入模板，再用 post.with 填写文章信息，相当于 Markdown 的 frontmatter：

#import "/src/typst/post.typ": *

#show: post.with(
  title: "我的文章",
  description: "一句话介绍内容",
  date: "2026-10-28",
  updated: "2026-10-28",
  tags: ("随笔", "示例"),
  draft: false,
)

文章页顶部是一级标题。正文的 = 会生成二级标题，== 到 ===== 依次生成三级到六级标题。

三级标题示例

这里是一个子章节。

四级标题示例

这里是更细的说明。

五级标题示例

标题层级继续往下。

六级标题示例

这是本页展示的最深一级标题。

段落、换行与转义

这是第一段。中英文可以写在一起：今天给小鸟准备了 12 颗种子。普通的源码换行仍然属于同一个段落；空一行才会开始下一段。

这是第二段。行末写一个反斜杠，可以明确换行：
这一句另起一行，仍然在同一个段落里。

需要显示标记本身时可以转义：*不是加粗*，_不是强调_，# 不是函数调用，$ 不是公式。行内代码也能保留这些符号：#show: post.with(…)。

行内文字

这里有加粗、斜体、加粗且斜体 和 ~~删除线~~。也可以在 加粗里面放一段斜体。

变量名写成 birdCount，命令写成 npm run dev。包含反引号的内容可以用原始文本函数表示：`seed`。

Typst 也能表达下划线、标记、H₂O 和 x²。键名可以用行内代码表示，例如 ⌘ + K。

链接与页内跳转

普通链接：Astro 官网。
把地址放进变量再复用：

Typst 官网，以及直接显示地址的 https://typst.app。

邮件链接：hello@example.com，这里只使用示例地址。
站内链接：阅读 Markdown 对照篇。
标签链接：回到行内文字，目标是标题旁边的 <inline-text>。

Markdown 的引用式链接由解析器整理地址；在 Typst 里，可以通过变量和 link 函数复用同一个目标。

引用

给文字留一点空白，也给读者留一点时间。

引用可以有多个段落，也可以包含强调和 代码。

这是嵌套引用，用来区分另一层声音。

引用里面也能放列表。

列表仍然按正常语法书写。

列表与任务

无序列表与嵌套

天空
- 云和远处的小鸟
- 细细的树枝
  - 树枝上的一片叶子
小鸟
1. 观察周围
2. 跳到种子旁边
3. 低头啄一下

有序列表与多段内容

写文章。

这是第一项的第二个段落，缩进后仍属于这一项。
在本地预览。
```
npm run dev
```
确认图片和链接都能打开。

需要从其他数字开始时，调用枚举函数：

检查排版。
提交到 Git。

完成状态与术语列表

Typst 没有 GFM 的任务框语法，这里使用完成与未完成符号，转换器会把它们显示为任务框：

准备两篇新的格式示例
补齐文字、表格和公式
把这里换成自己的文章
- 配一张合适的图片

术语列表则有原生写法，每一项以 / 开头：

Markdown: 用轻量标记组织内容，适合连续写作。
Typst: 把内容、函数和布局组合在一起，适合需要结构化排版的文章。

代码块与高亮

代码块和 Markdown 篇使用相同的高亮与复制按钮。Typst 的原始文本块同样使用反引号围栏，后面跟语言名：

type Bird = { name: string; seeds: number };

const birds: Bird[] = [
  { name: "蓝鸟", seeds: 4 },
  { name: "粉鸟", seeds: 7 },
];

const total = birds.reduce((sum, bird) => sum + bird.seeds, 0);
console.log(`今天准备了 ${total} 颗种子`);

新增、删除与重点行也可以直接标记：

const birdCount = 3;
const birdCount = 5;
const seedsPerBird = 4;
const total = birdCount * seedsPerBird;

不指定高亮语言时，保留原样展示：

small wings,
wide sky.

表格

table.header 指定表头，align 指定各列的对齐方式。单元格仍然可以使用行内格式：

小鸟	状态	种子数量
蓝鸟	观察中	4
粉鸟	`吃饭`	7
白鸟	休息	3
写法提示	`a\|b`	14

图片与图注

使用 image 引用本地图片，再用 figure 给它加上图注。这里和 Markdown 篇共用一张图片：

也可以把图片包在链接中，下面这张小图会跳转到 Markdown 对照篇；裁切排版的例子放在后半篇。

分隔线

line 会转换成网页里的分隔线：

这段文字位于分隔线之后。

脚注

脚注适合放不想打断正文的说明，比如这份示例使用的图片来源¹。脚注内容也可以分段²，会集中出现在文章末尾。

公式

行内公式使用一对美元符号，并让内容紧贴符号，例如 $a^{2} + b^{2} = c^{2}$ 与 $e^{i\pi} + 1 = 0$ 。公式两侧留空格时，会作为独立公式排版：

$\sum_{k = 1}^{n}k = \frac{n(n + 1)}{2},\quad\int_{- \infty}^{\infty}e^{- x^{2}}dx = \sqrt{\pi}$

矩阵、行列式和分段函数：

$A = \begin{pmatrix} 1 & 2 \\ 3 & 4 \end{pmatrix},\quad\det(A) = - 2$

$f(x) = \begin{cases} x^{2} & x \geq 0 \\ - x & x < 0 \end{cases}$

多行推导使用 & 指定对齐点，反斜杠换行：

$\begin{aligned} (a + b)^{2} & = (a + b)(a + b) \\ & = a^{2} + 2ab + b^{2} \end{aligned}$

Typst 的布局：网格与裁切

下面开始展示正文格式以外的能力。模板中的 crop 指定图片窗口、放大倍数和焦点；grid 用分数单位 fr 分配列宽。图片仍然是同一个文件，多次使用不需要保存多个裁切副本。

一张图片，三个视角

裁切图片可以点击查看完整原图。

跨行与跨列

左边的图片占两行，右边放两个局部，最后一张图片横跨两列：

图文并排

蓝白小鸟

这一段文字和图片并排，仍然可以选中、复制和搜索。

在较窄的屏幕上，本站会把这类图文网格改成单列，让文字排到图片下面。这是模板配合网页样式实现的效果。

Typst 的内容函数：写一次，重复使用

可以把重复的结构写成函数，放在以 _ 开头的辅助文件里。下面的 polaroid 位于本篇旁边的 _layouts.typ，不会被当成另一篇文章：

#let polaroid(img, caption) = div(class: "polaroid")[
  #img

  #caption
]

div 把内容交给已有的网页样式。stack 横向排列这些小相片，rotate 再给每张一点角度：

小鸟全身

午后

小鸟特写

特写

小鸟翅膀

翅膀

Typst 的变量、计算与循环

不需要把每一行都手写出来。下面用一个数组保存记录，通过循环生成列表，再计算总数：

蓝鸟：4 颗种子
粉鸟：7 颗种子
白鸟：3 颗种子

一共准备了 14 颗种子。

#let birds = (("蓝鸟", 4), ("粉鸟", 7), ("白鸟", 3))
#let total = birds.map(((name, count)) => count).fold(0, (sum, count) => sum + count)

#for (name, count) in birds [
  - #name：#count 颗种子
]

一共准备了 *#total 颗种子*。

这份示例的边界

Markdown 篇里的折叠区域、键盘标签和缩写提示属于 HTML 补充；本篇用 Typst 原生内容表达对应的文字格式，不把 HTML 当成 Typst 语法。

这里展示的是网页文章的排版，不是完整的 Typst PDF 页面引擎。页眉页脚、分页、绝对定位等页面功能没有在本篇使用；网格、旋转和裁切依靠本站模板与样式保留。写作时可以直接复制这些已经能转换成网页的例子。

图片复用自仓库已有的小鸟素材，保存在 src/content/article/_assets/bird.jpg，两篇示例共用同一个文件。↩︎
这是脚注的第一段。

这是同一条脚注的第二段，也可以包含强调、链接和代码。↩︎