企业官网建设流程全解析

Typst 如何启用实验性 HTML 导出？--features html 与用 target 区分导出目标的 show 规则

【免费下载链接】typstA markup-based typesetting system that is powerful and easy to learn.项目地址: https://gitcode.com/GitHub_Trending/ty/typst

如果你已经用 Typst 排版过 PDF，但希望同一份内容也能输出带语义结构的 HTML 页面（而不是图片化的视觉导出），需要完成两件事：通过--features html或TYPST_FEATURES环境变量打开实验性的 HTML 导出，并在文档里用target()函数区分导出目标，让 show 规则和模板函数针对不同目标生成不同表示。文档明确说明 HTML 导出目前仍在积极开发中、功能尚不完整，只开放实验使用，不要用于生产场景；Web 端应用暂不提供 HTML 导出。

启用 html 实验特性

HTML 导出默认关闭，必须显式启用。文档给出两种等价方式：

• 在命令上追加--features html；
• 将环境变量TYPST_FEATURES设为html。

以 bash 为例：

# 方式一：命令行参数 typst compile main.typ --format html --features html # 方式二：环境变量 TYPST_FEATURES=html typst compile main.typ --format html

main.typ替换为你的入口文件。没有开启特性时，--format html这个导出目标本身是不可用的，所以特性开关是第一步。

把文档导出为 HTML

对compile或watch子命令做两件事之一即可选中 HTML 目标：

• 传递--format html；
• 或者提供一个以.html结尾的输出文件名。

typst compile main.typ out.html --features html

使用typst watch时，Typst 会额外启动一个带 live reload 的 HTTP 服务来预览页面，相关参数（文档说明）：

• --port：修改端口，默认使用 3000-3005 范围内第一个空闲端口；
• --no-reload：禁用 live reload 脚本注入（写入磁盘的 HTML 不受影响）；
• --no-serve：完全不启动服务器。

用 target() 区分导出目标

target()函数返回当前编译目标，文档中的定义为：

• 在 PDF、PNG、SVG 导出（或 HTML frame 内部）时返回{"paged"}；
• 在 HTML 导出时返回{"html"}；
• 在 Bundle 导出时返回{"bundle"}。

该函数从 0.13.0 起可用，并且是 context 的：同一次 HTML 编译中，html.frame内部的target()会回到"paged"，所以分支判断要以它返回的当前值为准。

文档建议把target()主要用于模板函数和 show 规则，而不是直接写在正文里，这样正文内容对导出目标保持无知，同一份内容可以在 PDF 和 HTML 之间复用。

模板函数示例（文档示例）

target()文档给出的kbd示例，HTML 下用html.elem生成原生<kbd>元素，paged 下用带填充和描边的box模拟按键外观（以下为文档示例，数值来自原文档）：

#let kbd(it) = context { if target() == "html" { html.elem("kbd", it) } else { set text(fill: rgb("#1f2328")) let r = 3pt box( fill: rgb("#f6f8fa"), stroke: rgb("#d1d9e0b3"), outset: (y: r), inset: (x: r), radius: r, raw(it) ) } } Press #kbd("F1") for help.

给 show 规则加 if 守卫

在 show 规则末尾追加if target() == "paged"，可以让该规则只在分页目标下生效，HTML 导出时跳过。这是本仓库自身文档的排版组件反复使用的写法，例如 changelog 文档中就有：

#show heading: set heading(outlined: false, bookmarked: true) if target() == "paged"

可参考 docs/content/changelog/index.typ 与 docs/components/base.typ 中大量target() == "paged"守卫的实际用法，target() 函数定义与文档 位于源码crates/typst-library/src/foundations/target.rs。

反过来，也可以用if target() == "html"分支专门提供 HTML 表示，例如在模板函数里对 HTML 目标输出html.elem(...)原始 HTML 元素，对 paged 目标输出常规排版元素。

验证导出结果

按文档说明验证：

• html导出格式下，Typst 会输出单个 HTML 文件。执行上面的typst compile main.typ out.html --features html后，确认out.html被生成，并检查其中是否为语义化标记（而非纯视觉布局）。
• 如果走typst watch，验证方式是浏览器访问 3000-3005 端口范围内被选中的端口，页面随源文件修改自动刷新。
• 注意当前版本不输出 CSS：Typst 只输出语义标记，样式需要你自己写 CSS。文档说明未来计划支持自动生成 CSS 并纳入现有 set 规则。
• 如果 HTML 下某些布局规则没有生效，先确认它们是否带有if target() == "paged"之类的守卫——这是预期行为，不是导出失败。

需要多页站点时：bundle 目标

html格式一次只产出一个 HTML 文件。要用 Typst 生成由多个 HTML 文档和附加资源组成的网站，使用bundle目标：对compile/watch传--format bundle，并且必须同时启用两个特性，文档给出的写法是用逗号分隔：

typst compile main.typ --format bundle --features bundle,html

在 bundle 内用document元素声明各输出文件、asset元素写入任意原始数据，详见 docs/content/reference/export/bundle.typ。bundle 的target()返回"bundle"，守卫条件需要相应处理。

当前限制

汇总文档明确给出的边界：

• HTML 导出仍是实验特性，功能非常不完整，不要用于生产场景；
• Web 应用端目前不可用；
• 不输出 CSS，只输出语义标记；
• html与bundle目标目前都只输出独立完整的 HTML 文件，输出可嵌入其他 HTML 文档的片段只是未来计划；
• html.frame内部target()为"paged"，涉及 frame 的分支逻辑要以该值为准。

更多背景与完整参数说明见 docs/content/reference/export/html.typ 和 docs/content/reference/export/bundle.typ。

【免费下载链接】typstA markup-based typesetting system that is powerful and easy to learn.项目地址: https://gitcode.com/GitHub_Trending/ty/typst