近日，开源社区出现了一项引人注目的技术方案——将 Typst 排版系统生成的 HTML 内容无缝嵌入到 mdbook 构建的电子书中。这一创新瞬间打破了 Markdown 与专业排版之间的壁垒，为技术文档、学术论文乃至交互式出版物开辟了全新路径。

背景：Markdown 的局限与 Typst 的崛起

mdbook 是 Rust 生态中最受欢迎的静态站点生成器之一，被广泛用于编写技术书籍、API 文档和教程。它以 Markdown 为核心语法，简单易学，但对复杂排版（如数学公式、定制化表格、多栏布局、分页控制等）支持较弱。传统做法是嵌入 LaTeX 或 MathJax，但公式渲染尚可，整体排版能力依然受限。

与此同时，Typst 作为新兴的排版语言，正在迅速取代 LaTeX 的许多场景。它采用类似 Markdown 的简洁语法，却能生成媲美 LaTeX 的高质量 PDF、PNG 甚至 HTML 输出。Typst 支持自定义样式、变量、循环、自动编号，并能直接输出语义化的 HTML 结构——这为与 web 文档结合提供了天然桥梁。

技术方案：一种优雅的嵌入方式

社区实现的核心思路是：利用 Typst 的 --format html 参数将特定内容编译为纯 HTML 片段，再通过 mdbook 的 preprocessor 或自定义插件将其注入 Markdown 源文件中。整个流程无需修改 mdbook 核心，也无需额外服务端渲染。

具体而言，开发者可以创建一个 Typst 源文件（例如 figure.typ），其中包含复杂的图表、公式或带样式的文本块。在构建时，预处理脚本自动调用 typst compile figure.typ figure.html，生成一个干净的 HTML 片段。随后通过 mdbook 的 preprocessor 机制，将该片段以块级或内联方式替换 Markdown 中的占位符（如 {{typst:figure}}）。

更灵活的做法是使用 Typst 的 set document 指令自定义输出的 HTML 类名与结构，确保与 mdbook 的默认主题（如 gitbook、rustdoc 等）风格一致。例如，可以定义 #outline() 生成目录后直接嵌入 mdbook 的左侧导航栏。

实际案例：从科学论文到产品手册

一位早期采用者分享了其使用体验：在编写一本关于量子计算的 mdbook 时，需要大量精确排列的 Feynman 图和双栏注释。传统 Markdown 无论用表格还是图片都无法做到良好的跨页响应。通过 Typst，他直接使用 text 和 place 函数控制布局，输出 HTML 后嵌入 mdbook，最终在浏览器中实现了与 PDF 几乎相同的排版效果，且支持鼠标悬停高亮等交互。

另一个案例是某开源项目文档，利用 Typst 的 cetz 绘图库生成复杂网络拓扑图，再以 SVG 形式嵌入 mdbook。由于 Typst 输出的 HTML 直接包含可缩放矢量图形，用户无需安装额外字体或插件即可查看高清图。

优势与挑战：不止是“好看”

优势
- 排版一致性：同一份 Typst 源码可同时编译为 PDF（打印用）和 HTML（网页用），嵌入 mdbook 后保持视觉统一，避免手动调整。
- 动态内容：Typst 支持变量和函数，可在编译时传入参数，例如根据构建环境动态调整作者信息或版权声明。
- 性能与轻量：相比借助 Pandoc 或 WeasyPrint 进行转换，Typst 编译速度极快（通常在毫秒级），且生成的 HTML 无需额外 JavaScript 依赖。
- 协同编辑：Markdown 和 Typst 都是纯文本格式，团队可通过 Git 协作，无需解锁专有软件。

挑战
- 样式冲突：Typst 输出的 HTML 自带 CSS，可能与 mdbook 的主题样式冲突。解决方案是为 Typst 添加 body { all: unset } 或使用 Shadow DOM 隔离。
- 交互支持有限：Typst 的 HTML 输出目前仅支持基本的悬浮、点击效果，复杂的 Web 交互（如滑动条、实时计算）仍需借助 JavaScript 自行嵌入。
- 生态成熟度：这一方案尚处于社区实战阶段，缺乏统一的插件或模板库。用户需自行编写预处理脚本或熟悉 mdbook 的 preprocessor API。

未来展望：文档工具的融合趋势

此方案的出现，标志着“排版引擎”与“静态网站生成器”的界限正在模糊。随着 Typst 官方逐步完善其 HTML 输出（计划支持自定义模板、Web 字体、媒体查询），未来或将出现 typst-book 这样直接融合两者的工具。而对于现有 mdbook 用户而言，这一集成方式提供了极低的迁移成本——不需要重写现有文档，只需要在需要精细排版的章节引入 Typst 片段。

可以预见，在学术出版、技术手册、法规文档等领域，这种“Markdown 为主、Typst 为辅”的模式将成为主流。它既保留了 Markdown 的简洁协作性，又继承了 Typst 的专业排版能力——正如一位社区开发者所言：“我们终于可以在保持 git 友好性的同时，拥有 word 级别的排版控制力了。”

如果你正在使用 mdbook 构建文档，不妨尝试让 Typst 参与其中。从一段简单的公式排版开始，或许你会发现，文档的视觉表达力远比你想象的更有价值。