Typst for HTML 完全语法样例

= 一级标题示例

一级 Typst 标题用于正文分节。本站文章标题由页面显示，所以本文没有重复使用 `#title`。

== 二级标题

这是二级标题下的正文，检查字号、间距和标题导航。

=== 三级标题

这是三级标题下的正文。

==== 四级标题

这是四级标题下的正文，检查较深层级是否仍容易辨认。

===== 五级标题

这是五级标题下的正文。Typst 的一到五级标题在 HTML 中对应 h2 到 h6。

普通中文与 English 混排，包含数字 0123456789、中文标点「测试」（括号）和英文 punctuation。

这里有 *粗体*、_斜体_、*_粗斜体_*、`inline_code()`，还有 #strong[函数形式的粗体] 和 #emph[函数形式的强调]。

装饰测试：#underline[下划线]、#strike[删除线]、#highlight[高亮]、H#sub[2]O、x#super[2]。请检查导出后是否保留相应效果。

这一行末尾有显式换行。\
这一行应当接在同一段落中。

空行会另起一段。下面的特殊字符经过转义，应当按原样显示。

\#、\*、\_、\$、\@、\<、\>、\[、\]、\{、\}、\\。

不换行空格测试：Typst~HTML。Unicode 转义测试：\u{2713}。符号简写测试：A ... B -- C --- D。

// 这条单行注释不应出现在文章中。
/* 这条多行注释也不应显示。
   /* 嵌套注释测试。 */
*/

- 第一项有 *粗体* 和 `code`。
- 第二项包含嵌套列表。
  - 子项一。
  - 子项二包含 $a^2 + b^2$。
- 第三项恢复到外层。

+ 打开文章编辑器。
+ 粘贴整篇源码。
  + 等待预览编译完成。
  + 检查公式和链接。
+ 保存后检查文章页。

#enum(start: 4)[从第四项开始。][第五项。]

/ Typst: 本文使用的标记与排版语言。
/ HTML: 编译输出的网页文档格式。
/ MathML: HTML 中用于表达公式结构的标记。

自动链接：https://typst.app/。

显式链接：#link("https://typst.app/docs/")[Typst 官方文档]。

邮件链接：#link("mailto:test@example.com")[test\@example.com]。

标题链接应跳到 #link(<test-headings>)[标题与段落]，这种写法不依赖标题编号。

编号引用的写法是 `@test-headings`，使用前需要在标题出现之前设置 `#set heading(numbering: "1.1")`。

行内引用：#quote[这是一句用于测试的文字。]

#quote(block: true, attribution: [测试文章])[
  引用块中的第一段带有 *强调* 和 #link("https://typst.app/")[链接]。

  第二段用于检查引用块内部的段落间距。
]

这里有第一条脚注。#footnote[第一条脚注，含有 _强调_。]
这里有第二条脚注。#footnote[第二条脚注，含有 #link("https://typst.app/docs/")[文档链接]。]

行内代码 `const message = "你好"` 应当与正文基线协调。

```typ
= 示例标题
这段代码中的 *粗体* 和 $x^2$ 不会被执行。
#link("https://typst.app/")[文档]
```

```rust
fn main() {
    let message = "你好，Typst HTML";
    println!("{message}");
}
```

```json
{
  "title": "中文标题",
  "published": false,
  "tags": ["Typst", "HTML"],
  "escaped": "<div>& text</div>"
}
```

```
没有指定语言的代码块。
保留    连续空格
    保留缩进
```

这一行故意很长，用于检查代码块是否能独立横向滚动。

```text
https://example.com/articles/typst-html-syntax-test?first_parameter=abcdefghijklmnopqrstuvwxyz&second_parameter=012345678901234567890123456789&third_parameter=abcdefghijklmnopqrstuvwxyz
```

行内公式 $E = m c^2$、$a_i$、$alpha + beta <= gamma$ 应当与文字一起自然换行。

$ x = (-b plus.minus sqrt(b^2 - 4 a c)) / (2 a) $

$ sum_(k=1)^n k = (n(n+1))/2 $

$ integral_0^1 x^2 dif x = 1/3 $

$ lim_(x -> 0) (sin x)/x = 1 $

$ A = mat(1, 2; 3, 4), quad v = vec(x, y, z) $

$ abs(x) = cases(x & "当" x >= 0, -x & "当" x < 0) $

$ (a + b)^2 &= a^2 + 2 a b + b^2 \
  (a - b)^2 &= a^2 - 2 a b + b^2 $

#math.equation(block: true, numbering: "(1)")[$ a^2 + b^2 = c^2 $] <test-equation>

这里引用 @test-equation，检查编号和跳转。

#figure(
  table(
    columns: 3,
    table.header([语法], [测试内容], [检查结果]),
    [文本], [*粗体* 与 _斜体_], [样式保留],
    [公式], [$x^2 + y^2$], [公式完整],
    [链接], [#link("https://typst.app/")[Typst]], [能够点击],
    [长内容], [这是一段较长的单元格文字，用于观察窄屏下的换行和表格宽度。], [人工检查],
    table.cell(colspan: 2)[这一格跨两列。], [合并单元格],
    table.cell(rowspan: 2)[这一格跨两行。], [第一行], [A],
    [第二行], [B],
  ),
  caption: [正文语法检查表],
) <test-table>

这里引用 @test-table。表格编号、图注和链接应当对应同一张表。

下面直接给 `table` 添加标签，点击 #link(<plain-table>)[跳到独立表格] 应当定位到表格顶部，并避开导航栏。

#table(
  columns: 2,
  table.header([项目], [内容]),
  [锚点], [`plain-table`],
  [跳转方式], [`#link(<plain-table>)[链接文字]`],
) <plain-table>

独立表格使用 `#link` 跳转。如果需要 `@test-table` 这样的自动编号引用，请使用上面的 `figure(table(...)) <test-table>` 写法。

下面的图片由源码内的 SVG 数据生成，不依赖本地路径或外部网络。

#let test-svg = bytes("<svg xmlns='http://www.w3.org/2000/svg' width='480' height='160' viewBox='0 0 480 160'><rect width='480' height='160' fill='#eee8f6'/><circle cx='80' cy='80' r='42' fill='#7d4fc4'/><rect x='156' y='44' width='268' height='24' fill='#403b44'/><rect x='156' y='92' width='180' height='16' fill='#9a70d6'/></svg>")
#figure(
  image(test-svg, format: "svg", width: 100%, alt: "浅紫底色上的紫色圆形与两条横线，用于检查图片缩放。"),
  caption: [内嵌 SVG 图片],
) <test-image>

这里引用 @test-image。请检查图片没有超出正文区域。

#let article-name = "Typst for HTML"
#let values = (2, 4, 6)
#let options = (format: "HTML", enabled: true)
#let double(x) = x * 2

变量插值：#article-name。算术表达式：#(2 + 3 * 4)。函数结果：#double(6)。

字典字段：#options.format。数组索引：#values.at(1)。数组转换：#values.map(double).map(str).join("、")。

#if options.enabled [条件分支已启用。] else [条件分支已关闭。]

#for (index, value) in values.enumerate() [
  - 第 #(index + 1) 项的值是 #value。
]

#let badge(body, prefix: "提示") = [*#prefix*：#body]
#badge(prefix: "函数参数")[这里测试命名参数与内容块。]

#let sum-all(..args) = args.pos().sum()
参数展开：#sum-all(..values)。

#let (first, ..rest) = values
解构结果：#first；剩余项：#rest.map(str).join("、")。

#let countdown() = {
  let n = 3
  let result = ()
  while n > 0 {
    result.push(str(n))
    n -= 1
  }
  return result.join(" → ")
}
循环与返回值：#countdown()。

下面的规则仅在内容块中生效。

#[
  #set enum(numbering: "a)")
  + 局部编号的第一项。
  + 局部编号的第二项。
]

#[
  #show "PLACEHOLDER": [替换成功]
  show 规则结果：PLACEHOLDER。
]

#context [当前导出目标是 #target()。]

#let test-counter = counter("syntax-example")
#test-counter.step()
当前计数：#context test-counter.display()。

#let test-state = state("syntax-example-state", "初始值")
#test-state.update("已更新")
当前状态：#context test-state.get()。

#metadata("metadata-ok") <test-metadata>
元数据查询：#context query(<test-metadata>).first().value。

下面直接生成 HTML 元素，用于检查浏览器里的语义标签和交互。

#html.elem("p")[
  键盘按键：#html.elem("kbd")[Ctrl] + #html.elem("kbd")[S]。
  HTML 标记：#html.elem("mark")[需要检查的文字]。
]

#html.elem("details")[
  #html.elem("summary")[展开查看测试说明]
  #html.elem("p")[这段文字应当随折叠区域展开或收起。请用鼠标和键盘分别操作。]
]

#html.elem("div", attrs: (id: "syntax-custom-anchor"))[
  这是带有自定义 ID 的区域。
]
#link("#syntax-custom-anchor")[跳转到自定义区域]。

类型化 HTML 函数测试：#html.abbr(title: "HyperText Markup Language")[HTML]。

#let keyboard(body) = context {
  if target() == "html" {
    html.elem("kbd", body)
  } else {
    strong(body)
  }
}
函数生成的按键名称：#keyboard[Enter]。

下面的几何图形放在 `html.frame` 中，检查生成的 SVG 是否完整。

#html.frame[
  #stack(dir: ltr, spacing: 12pt,
    rect(width: 64pt, height: 40pt, fill: rgb("#eee8f6"), stroke: rgb("#7d4fc4")),
    circle(radius: 20pt, fill: rgb("#7d4fc4")),
  )
]

#let payload = json(bytes("{\"name\":\"HTML\",\"count\":3}"))
内嵌 JSON 解析结果：#payload.name，共 #payload.count 项。

这里使用参考文献引用 @typst-docs。

#bibliography(bytes("@misc{typst-docs, title={Typst Documentation}, author={{Typst}}, year={2026}, url={https://typst.app/docs/}}"), style: "ieee", title: [参考文献])

本站编译器以临时渲染目录为根目录。下面的代码仅供测试时替换路径，不会实际执行。测试上传图片时，应使用编辑器上传按钮插入的路径。

```typ
#image("实际上传后的图片路径", width: 100%, alt: "图片内容说明")
#import "helpers.typ": helper
#include "chapter.typ"
#let data = json("data.json")
#let rows = csv("data.csv")
#bibliography("references.bib")
```

`import`、`include`、文件读取与第三方包需要单独准备依赖。PDF 的页眉、页脚、分页和多栏排版也应另做测试，不应期待它们在 HTML 中自动保持同样的外观。