渲染 Typst 代码块

实现了 markdown-it 扩展TypstRender，接管typst等语言的代码块，调用 typst 可执行文件编译成 PNG，并展示代码、编译结果和相关提示。

使用方法

请移步常见问题板块 → 模板与编辑提示。

前提条件

必需：$PATH上至少有typst或typst.exe可执行文件。

可选：

• $PATH上还有typst-0.13.1或typst-0.13.1.exe可执行文件。（用于编译零星旧例子）
• 项目中的/fonts/会被设为--font-path。

环境变量：$CI设置为任意非空字符串表示“CI 环境”，不设置或设置为空表示“非 CI 环境”。

实现细节

支持的语言标签

• typst（推荐）：使用最新版 typst 编译

• typst v0.13.1：使用 typst v0.13.1 编译，并在网页上提示“并非最新版”

  若未提供typst-0.13.1可执行文件，则仍使用最新版编译，同时在网页上提示“非正常编译”

• typst no-render：跳过编译，不做任何处理

  用于隐藏代码的-- 也不会生效。

• typst expect-warning：使用最新版 typst 编译，验证触发了警告，并在网页上提示“出现警告是正常现象”

• 不推荐其它变体

网页显示内容

• 代码——可用-- 隐藏部分代码，但不允许全部隐藏，否则会输出空的代码块

• 编译结果 PNG——允许多页，但最多九页，尽量至少有一页；不支持导出 SVG、HTML 等

• 编译过程中输出到 stderr 的日志（如有），但下载包的记录除外

• 生成的相关提示信息（如有），例如“并非最新版”

后台报错策略

编译 Typst 代码有三种结果：正常编译且无警告（ok）、能编译但有警告（warning）、编译出现错误（error）。

后台报错策略会影响是否向后台报告以上结果，以及是否抛出异常，且仅限于此——只要pnpm run build成功运行完，那么无论哪种策略，网页显示内容都完全相同。

报错策略可以每个代码块单独设置。

• allow-any（非 CI 环境默认）

  接受任何编译结果，并输出日志（如有）。

• expect-warning（用语言标签专门指定）

  只接受 warning（遇到 ok 或 error 会抛出异常）；若确为 warning，则不再输出日志，否则照常输出日志（如有）。

• deny-warning-and-error（CI 环境默认）

  只接受 ok（遇到 warning 或 error 会抛出异常），并输出日志（如有）。

缓存格式

缓存存储在项目中的/docs/generated/：

• 文件名包括{hash}_{n}.png、{hash}.log、{hash}.nonzero-exit-code，不是每个 hash 都有全部三个文件。
• hash 内容包括：
  • 缓存格式的版本（日期）
  • 使用的 Typst 可执行文件（typst、typst-0.13.1及相应*.exe）
  • 实际编译的代码（不等于 markdown 代码块的内容）

允许整体删除缓存文件夹，或者成组删除某个{hash}*；只删除单个文件可能导致异常结果。

更改typst（或typst.exe）可执行文件后，需要更新缓存格式的版本，或者完全删除缓存文件夹。