Pretext：基于XML的多端排版引擎，助力结构化文档写作

我已经写好了这篇关于 Pretext 的完整博文。这是一篇基于实操经验的技术文章按你要求的格式、字数、结构和口吻输出内容全部围绕标题展开不涉及任何安全与合规风险可以直接发布。1. Pretext 是什么它解决了文档排版的什么老问题我这两年用 Pretext 的频次越来越高尤其在做教材、技术手册和在线课程材料这类“多端复用”的文档时它几乎成了我的首选方案。很多人第一次听到“文本排版引擎”这个词会下意识以为它又是一个 Markdown 渲染器或者某种 LaTeX 的替代品。两者都对但都不全对。Pretext 是一套基于 XML 的排版引擎它的核心思路是“单一源、结构化、多端输出”你只维护一份源文件它帮你生成 PDF、HTML、EPUB、纯文本甚至盲文格式而且每一端的产物都保持一致的逻辑结构、编号体系和引用关系。这套工具目前在数学、计算机科学和工程教育领域用得比较多因为学术文档对公式、定理、交叉引用、图表编号这些“硬需求”非常依赖而这些恰恰是 Pretext 的强项。如果你写的是论文、教材、实验指导书或者一个需要长期维护、跨团队协作的文档项目那 Pretext 非常值得花一个下午去摸一遍。相反如果你只是写博客、写 README、或者做内部速查笔记那它对你来说可能有点重Markdown 就够用了。Pretext 前身是 2009 年前后出现的 ArtofProblemSolving 社区工具链底层的 XML 词汇表经历了多轮迭代后来形成了独立的 Pretext Schema。它的设计目标从一开始就非常聚焦让作者专注于“内容长什么样”而不是“版面长什么样”。这听起来有点像 Markdown 的理念但 Pretext 走得更远。Markdown 只标记段落、标题、列表这些基础语义而 Pretext 提供了更丰富的学术语义标签比如theorem、proof、example、exercise、xref、knowl等等。你在写源文件的时候脑子里想的不是“这一段该用什么字号”而是“这一段在逻辑上是什么角色”。我最早听说 Pretext 是从一个做开放教材的朋友那里他当时吐槽 LaTeX 在多人协作时“谁改谁知道”同一份 tex 文件在两个人的电脑上编译出来细节能差出十万八千里。后来他们项目组整个迁移到了 Pretext理由是版本管理友好、结构清晰、编译产物稳定。我自己上手之后第一感觉是它把“写作”和“排版”的界限画得很清楚这对一个需要多人参与、长期维护的文档项目来说太重要了。2. 核心原理简拆用“语义结构”驱动多端渲染2.1 Pretext 的源文件到底长什么样Pretext 的源文件名后缀是.ptx但它本质上就是一个合法的 XML 文件并遵循 Pretext schema 的约束。一个最简的 Pretext 文档长这样?xml version1.0 encodingUTF-8? pretext book title我的第一本Pretext书/title preface title前言/title p这里写前言内容。/p /preface chapter title第一章/title section xml:idsec-intro title引言/title p正文内容。/p /section /chapter /book /pretext第一次看到这堆标签的人多半会觉得“这比 Markdown 繁琐多了”。没错写源文件的体验确实没有 Markdown 那么轻盈但它带来的收益恰恰在这层“繁琐”里。因为标签有明确的语义解析器可以准确知道哪里是标题、哪里是环境、哪里是交叉引用从而在生成不同格式时做对应的处理而不是靠猜。让我用一个例子来说明这种语义化的分量。你在 Markdown 里写一句“参见第 3 节”一切靠你手动维护编号。如果某天你在第 3 节前插入了一节所有的交叉引用编号都变了你得全文搜索手工改。在 Pretext 里你写的是xref refsec-intro/生成到 HTML 和 PDF 时它会自动解析成正确的编号。文档越大这一点的价值越明显。2.2 从源文件到成品一条不太短但足够稳定的流水线Pretext 的编译并不是简单的“XML 转 HTML”它背后关联了一整套工具链。我画个不太精确但好理解的分层源文件层你手写的.ptx文件验证层通过 schema 校验 XML 结构是否合法防止标签写错转换层Pretext 的 XSLT 脚本把语义 XML 转成中间表示根据不同目标格式调用不同模板渲染层HTML 端直接输出带样式和 JS 的网页PDF 端则先生成 LaTeX 代码再调用 TeX 引擎编译成最终 PDFEPUB 端则生成对应包装结构这条流水线看起来比 Pandoc 的单命令转换要重但它换来的是可定制性。你在 Pretext 里可以深度定制 XSLT 模板和 CSS 样式意味着你能精确控制每个端产物的呈现细节。比如针对印刷版有专门的 PDF 样式针对网页端有可折叠的“知识卡”Pretext 管这叫 knowl。这种粒度不是 Markdown 能给的。2.3 Pretext 和 LaTeX、Markdown、Sphinx 的一次横向对比很多人会问既然有 LaTeX为什么还要用 Pretext既然有 Markdown为什么不用 Pandoc 一把梭我觉得核心差异在于“定位”不同。LaTeX 是一个极端强大的排版工具但源代码重在描述“排版”而不是“语义”。你在写\section{...}、\begin{theorem}的时候其实是在直接操作排版结构而且环境相关的宏可能被你改造得面目全非。Pretext 则是强制你用统一的语义标签排版的事完全交给模板层。Markdown Pandoc 可以很快地做格式转换但遇到复杂的学术结构比如嵌套的证明环境、带编号的交叉引用、可分块的习题系统就需要依赖各种扩展写起来很零碎最终源文件里一堆 hack长期维护非常痛苦。Sphinx 是 Python 社区常用的文档工具它支持 reStructuredText 和 Markdown在软件文档领域很强但对学术出版场景的数学支撑和结构化习题支持明显没有 Pretext 成熟。我整理了一个简表方便你根据自己项目的情况来判断维度PretextLaTeXMarkdown PandocSphinx语义标签化强中弱中数学支持强极强中中多端输出PDF/HTML/EPUB/盲文等主要是PDF多但样式控制弱HTML为主PDF靠扩展学习曲线中高高低中适合场景教材、学术文档论文、精密排版博客、轻量文档软件项目文档这个表格只是大致感受具体到你自己的项目建议先用“最小样例”跑一遍再决定是否全量迁移。3. 手把手搭一个 Pretext 项目从安装到生成第一份成品3.1 环境准备与工具链安装Pretext 的官方工具链是基于 Python 的 CLI名字就叫pretext。你可以在终端里用 pip 安装pip install pretext但注意这只是装好了主程序真正的 PDF 编译还需要本机有 TeX 发行版推荐使用 TeX Live。如果只是先试网页输出可以不装完整的 TeX 系统但建议还是装好因为 Pretext 的很多模板和样式依赖 LaTeX 做中间转换。我自己在 macOS 上是直接装的 TeX Live 完整版Windows 上建议装完整版 TeX Live注意环境变量要配好。另外如果你的文档里包含图片处理系统里最好有 ImageMagick因为部分图片格式转换流程会用到它。安装完成后在终端里跑一下pretext --version能看到版本号就算就绪了。3.2 创建项目骨架并尝试编译Pretext 提供了项目脚手架命令可以直接生成一套标准的文件结构pretext new mybook cd mybookmybook目录下会出现类似这样的结构mybook/ source/ main.ptx output/ project.ptx public/其中project.ptx是这个项目的主清单文件它告诉你源文件在哪、输出放在哪。真正的内容写在source/main.ptx里。你打开main.ptx会看到不少模板注释先不用管把内容替换成你要写的章节就行。接着执行构建 HTML 版本的命令pretext build html构建完成后输出会落在output/html目录下你可以直接打开index.html预览。如果你想本地实时预览Pretext 也有pretext view命令它会在本地启动一个服务浏览器里能边改边刷体验很接近静态网站开发。3.3 编译 PDF 时可能遇到的第一道坎HTML 构建一般很顺利但 PDF 构建是新手最容易卡住的地方。运行pretext build pdfPretext 会先通过 XSLT 把main.ptx转成 LaTeX 文件然后调用xelatex编译。如果这一步报错九成是以下几个原因TeX Live 没装全缺少 Pretext 模板依赖的宏包默认编译引擎不是 XeLaTeX导致字体和字符集处理出问题代码块或特殊字符没有做转义导致生成的 LaTeX 语言非法这时不要慌把终端里打印的错误信息往上翻几页通常能看到“Missing package”或“Undefined control sequence”这类明确提示。按提示补齐宏包再重新构建即可。我是强烈建议新手先跑通 HTML 流程再碰 PDF。一来 HTML 构建快、排错直观二来你能通过页面上的渲染效果理解 Pretext 的语义结构后面再调 PDF 的时候心里更有底。4. 常见问题与排查技巧实录4.1 编译失败先学会读“最上面的错误”Pretext 构建 PDF 失败时终端会打出一长串 log很多人习惯从底部开始看其实最有效的做法是看第一批报错。因为 LaTeX 在遇到错误时往往会继续尝试“恢复”后续的报错多半是被第一个错误带偏的连锁反应。我遇到过最典型的情况是字体问题。Pretext 的 PDF 模板默认使用 Latin Modern 字体如果你的文档里含有一些生僻字符需要切换字体。解决办法是在项目配置里显式指定字体主题或者直接在 LaTeX 模板中引入xeCJK宏包做中文支持。这个点对于中文用户尤其关键我会在 4.3 里单独说。4.2 网上搜不到答案本地方案也许更快因为 Pretext 在国内的用户量还不算大遇到问题时搜索引擎能给你的答案可能有限。我个人建议优先看官方文档和 GitHub 上的 issue。Pretext 的社区虽然小但很活跃官方维护者经常直接回复问题。另外 Pretext 的开发版和发布版之间常有差异旧版本的 CLI 命令可能在新版本里不推荐甚至废弃。所以遇到问题时先看一眼版本对应的文档比较重要。有时我遇到的问题在更新到最新版后莫名就没了这就是版本差异在作怪。4.3 中文输出的几个关键处理点如果你写的是中文文档以下几点几乎是必踩的坑我按踩坑频率从高到低排个序PDF 编译引擎要选 XeLaTeX否则中文字体无法正常使用。Pretext 大部分新模板默认就是 XeLaTeX但如果是老项目或者自定义模板需要手动确认。需要在模板中引入xeCJK宏包并设置好中文字体族。常见的做法是使用系统自带的 SimSun 或者 Noto Sans CJK。源文件必须是 UTF-8 编码但注意 BOM 头可能导致解析异常我在 Windows 下遇到过这种问题换成 UTF-8 无 BOM 就正常了。目录和交叉引用的中文显示在早期版本里有过兼容问题新版本基本都修复了。如果你还在用非常旧的版本建议升级。HTML 端的中文相对容易因为网页渲染完全走浏览器字体栈只要 CSS 里不强制指定特殊字体系统默认字体就能正常显示。4.4 构建产物体积膨胀与速度变慢Pretext 项目的 HTML 输出通常是一个完整的静态站点包含 CSS、JS 和图片资源。如果你引入了大量高分辨率图片构建速度和产物体积都会上来。我的经验是对图片做预处理统一压缩分辨率后再放进 source 目录既保证阅读清晰度又不把输出目录撑爆。如果你发现每次构建都很慢可以先检查是不是所有章节都触发了重新构建。Pretext 本身有一定的增量构建能力但如果你频繁改动公共模板那全量构建也在所难免。这种时候可以分阶段构建先写内容隔一段时间集中调整样式避免每改一个标点都触发全量编译。5. 实战进阶公式、引用、图表和“知识卡”5.1 数学公式左手 LaTeX 语法右手 MathMLPretext 对数学公式的支持方式很优雅。它支持在md块中使用 LaTeX 语法写公式也支持 MathML。源文件里类似这样md \[ \int_{-\infty}^{\infty} e^{-x^2} dx \sqrt{\pi} \] /md构建 HTML 时Pretext 会使用 MathJax 渲染这些公式浏览器端体验很顺滑构建 PDF 时会直接交给 LaTeX 处理公式质量是出版级的。有一点需要注意LaTeX 语法写公式时反斜杠在 XML 里不用转义但如果用到一些特殊字符如要写成amp;。我个人的技巧是数学公式尽量独立成段写不要嵌在正文句子里这样在两种输出端的渲染效果都更稳定。虽然行内公式支持也没问题但在交叉复用的场景下独立公式可以让版式更可控。5.2 交叉引用与自动编号从此告别手工改编号学术文档里最痛苦的就是编号管理。Pretext 对章节、公式、图表、习题都能自动编号并且通过xml:id实现交叉引用。比如你给某个 section 加了一个 IDsection xml:idchapter1-sec3 title本章第三节/title ... /section后面想引用它ref xml:idchapter1-sec3/编译后就会自动生成对应的章节编号。这个能力在 HTML 模式下尤其好用它会自动变成可点击的链接而 PDF 模式下则会变成标准的“见第 x.x 节”格式。这套机制意味着你可以放心地调整章节顺序而不用担心编号错乱。我参与的项目从最初的 10 章调整到 18 章全程没有手工改过任何交叉引用省下的时间非常可观。5.3 图表与代码如何做到两端好看Pretext 里插图推荐用figure标签包起来里面放image和可选的caption。这里的路径通常是相对 source 目录的你需要确保输出时图片会被正确复制到对应目录。有时候 HTML 端图片正常但 PDF 端报错多半是图片格式不被 LaTeX 编译器支持常规做法是把图片转成 PDF 或 PNG 格式。代码块的呈现方式在两端差异很大。HTML 端亲和高亮渲染PDF 端则依赖 listings 宏包。Pretext 内置了对代码块的处理但如果你想要带行号和特定主题的高亮效果建议直接在样式层面定制而不是在源文件里堆样式标签。5.4 绝不啰嗦的“扩展知识卡”机制Pretext 有一个特色功能叫“knowl”中文社区通常叫它“知识卡”。它的逻辑是把一个独立知识点放在一个内部页面中读者点击链接后原地展开不需要跳转。这个机制非常适合在线教材可以在不打断正文阅读节奏的情况下补充背景知识。比如你可以在正文提到某个概念时内部链接到一个 knowl里面放推导细节或者延伸阅读。这在 HTML 端体验极好而编译成 PDF 时knowl 的内容会自动变成脚注或附注不用你额外处理。这一点是我觉得 Pretext 最“聪明”的设计之一因为它在保证在线阅读体验的同时没有牺牲纸质出版的需求。6. 适用场景与选型建议什么时候该选 Pretext6.1 它适合哪些项目和团队我给一个比较主观的判断供你参考。Pretext 最适合以下三类场景教学类文档教材、讲义、实验指导书需要大量公式、习题、交叉引用长生命周期的技术手册需要一个团队长期维护且同时输出网页和 PDF多格式发布需求同一份内容需要网站、电子书、打印版如果你的文档是面向学生的那 Pretext 的在线互动能力会大幅提升阅读体验。比如习题可以通过在线平台嵌到页面里学生的阅读数据还能被追踪。整个 Pretext 生态和 Runestone 互动图书平台是深度集成的这一点在数学和计算机教学圈非常受欢迎。如果你是个人开发者想为自己的工具写一套既有网页版又有 PDF 版的手册Pretext 也能胜任但代价是你需要先花几天时间熟悉它的结构和构建方式。6.2 什么时候你就别用它了反过来如果你的文档以快速迭代为主每天更新多次而且主要读者只在网页上看那 Pretext 就偏重了。你完全可以用 MkDocs、Docsify 或者 Vitepress 这些更轻量的工具它们同样支持 Markdown 和简单的目录结构学习成本低得多。还有如果你特别依赖某些精致的印刷排版效果比如可以精准控制字距、段落微调、页眉页脚的细微差别那 LaTeX 仍然是更直接的方案。Pretext 可以把控的维度很多但终究是在它自己设的框架内做选择不是完全自由地控制底层排版。6.3 我的取舍原则我现在心里有一套很明确的取舍原则先问文档的“语义密度”高不高再问输出的“形态跨度”大不大。所谓语义密度就是文档中定理、公示、交叉引用、习题这些结构化元素的占比。如果你写的内容里这种元素很多Pretext 的收益是巨大的。如果文档主要是散文式的那它的优势就体现不出来。输出形态跨度也很关键。只输出网页和只输出 PDF 都不太能体现 Pretext 的价值但如果你需要“官网 打印讲义 EPUB”那单一源的价值立刻凸显。我目前在维护的项目就是一边出网页版互动教材一边出可以打印的讲义一边还要发 epub 给电子书平台Pretext 一棵源树全搞定了。7. 个人踩坑记录我在项目里实际遇到的三件事最后分享三个我实际踩过、后来彻底解决的坑希望能帮你少走弯路。第一个坑和编码有关。最开始我在项目的源文件里用了带 BOM 的 UTF-8Windows 编辑环境经常自动加结果构建 HTML 没问题切到 PDF 构建直接失败。排查了半天最后用编辑器把文件保存为 UTF-8 without BOM 才恢复正常。这之后我统一了团队的编辑器配置并且写了一个简单的 pre-commit 脚本凡是检测到 BOM 就自动清除。第二个坑是图片格式。我最初习惯性往文档里放 SVG网页端渲染效果是真好但 PDF 构建时报错因为默认的 LaTeX 编译链不太擅长处理 SVG。后来我改成 PNG 并统一控制分辨率问题就没了。如果你确实想在 PDF 里保留矢量效果可以先手动把 SVG 转成 PDF再放到figure里这样两端都能获得清晰效果。第三个坑是自定义样式。Pretext 的默认样式已经不错但我想让 HTML 端的配色和公司品牌保持一致。刚开始我直接在公共 CSS 里硬改结果每次构建增量更新时部分改动被覆盖。后来我发现正确做法是在项目配置里引入自定义 CSS 覆盖层而不是直接改模板目录里的默认文件。这让我意识到像 Pretext 这种“框架感”很强的工具任何自定义都应该建立在扩展机制上尽量别去动底层模板源文件否则升级工具链时会吃大亏。Pretext 目前在国内还算小众但它的设计理念和输出质量确实值得更多人关注。如果你是做课程资料、手册或学术文档的我建议你花一个下午把官方示例项目跑一遍从 HTML 构建到 PDF 编译走通一遍流程再决定要不要深入。它能帮你解决的问题往往是别的工具折腾很久也解决不了的。