提起文本排版引擎很多人第一时间想到的是 LaTeX、Pandoc或者 Word 里那套让人又爱又恨的样式系统。今天我想聊的是一个相对小众但非常值得关注的项目Pretext。简单说Pretext 是一个面向结构化长文档的文本排版引擎作者只负责写内容和语义结构剩下的 HTML、PDF、EPUB 输出全部交给引擎去处理。它特别适合技术手册、在线课程、教材这类“一次编写、多处发布”的场景也适合那些已经被 Markdown 和 Word 折腾到崩溃的内容团队。如果你正在找一条能同时兼顾印刷质量、网页体验和长期维护的路Pretext 值得你花一个周末认真试一试。1. Pretext 到底解决什么问题1.1 被标记语言“框住”的作者们先说说我自己踩过的坑。早几年写博客的时候我一直用 Markdown轻快是真轻快不需要学习什么炫酷语法打开编辑器就能写。可一旦文档规模变大问题就接踵而至脚注还能忍交叉引用就有点别扭到了“给同一个术语生成索引”“根据文章结构变化自动更新目录”“同一份内容既要出网页版又要出排版精美的 PDF 讲义”这些需求时Markdown 基本就力不从心了。于是很多人转向 LaTeX。LaTeX 的排版质量确实没话说尤其是学术论文、数学公式、复杂表格几乎是无敌的存在。但它的代价同样明显语法门槛高光是把字体、页面边距、标题层级这些“样式细节”调明白就足以劝退一批怀抱写作理想的人。更关键的是LaTeX 作者往往在写内容的同时还要分心去维护一堆排版命令内容与表现搅在一起后期改版时牵一发而动全身。Word 则是另一个极端。打开即写所见即所得大部分办公场景都能对付。但长文档一到多人协作就变灾难样式漂移、目录不同步、页码错乱、图注编号失踪再加上不同 Office 版本之间兼容性差异文档越改越像一个装满雷的地下室谁都不敢轻易碰。Pretext 的切入点是为什么不把“内容该说些什么”和“内容看起来什么样”彻底拆开作者只标记“这是一个章节标题”“这是一段警告”“这是一个引用来源”而不是直接指定“这里是黑体三号居中”。排版引擎拿到语义化标记后再根据你选择的目标格式去渲染成漂亮的页面或严谨的印刷稿。这种思路并不算激进DocBook、DITA 等老牌方案早就验证过但 Pretext 在数学排版、Web 输出、课程资料场景上做得格外顺手。1.2 Pretext 的定位给长文档和结构化内容用的排版引擎如果要用一句话概括Pretext 是一个“以 XML 语义标记为源文件面向书籍、教材、技术文档的文本排版引擎”。它不像 Word 那样让你看到最终效果也不像 Markdown 那样让你用最少的符号完成轻量排版。它更像是一套工厂流水线输入是结构清晰的源文件输出是多种终端产品。我更愿意称它为“结构化作者的生产工具”。因为它的根元素通常是book、article、webpage这类语义化容器内部由chapter、section、p、figure、xref等结构标签组成。作者写的不是“某一段用什么格式显示”而是“这一段在小节结构中的位置是什么、和哪些内容存在引用关系”。这种定位带来一个很实际的好处改版效率极高。我可以先给团队做 HTML 版本文档站让读者在浏览器里直接阅读再用同一套源文件编译 PDF 版讲义投递给印刷厂。传统工作流里这两套产物往往需要人工同步改了网页忘了 PDF 是常态。Pretext 里它们只是同一次构建的不同目标内容永远只有一份。当然Pretext 不是万能钥匙。如果只是写几百字的随手笔记或者需要高频改动表格样式它的上手成本未必划算。它最舒服的领域是内容量大、结构稳定、需要长期维护和多次发布的场景。我在实际项目中见过的典型使用人群包括大学老师教材与课件同步、开源项目维护者在线文档与 PDF 手册同步、制造业企业技术规范与培训材料同步还有做内部知识库的团队。2. 拆解 Pretext 的核心设计怎样的排版引擎才值得关注2.1 语义化写作内容与样式彻底分离“语义化写作”这个词听起来很抽象我用一个生活化类比解释一下。小时候玩积木每一块积木都有自己的形状有的是长条有的是方块有的是拱门。你可以用同样一堆积木搭出欧洲城堡也可以搭出中式庭院。积木本身没有变成城堡或庭院是搭建方式和外部装饰决定了最终风格。Pretext 的源文件就是那堆积木。你用title声明一个标题用p声明一个段落用figure声明一张图。至于这个标题是显示成黑体还是宋体段落之间要不要缩进图片在页面上是居中还是靠边那是排版引擎和样式表的事不归源文件管。这种分离带来的影响是深远的。首先目录和交叉引用可以自动生成。因为排版引擎知道哪些标签属于标题层级它可以在预处理阶段数一下结构然后自动生成完整的目录。当我在第二章里插入一个“见第三章第四节”的引用时不需要手写编号只要写xref refsome-section-id/最终生成的每个格式里都会自动填入正确的编号。其次无障碍可访问性更好。HTML 输出里section、nav、figure这些元素能正确映射到浏览器的语义结构屏幕阅读器可以更准确地理解内容层次。这对做公开教学网站或者政府类信息服务的人来说是一项隐形的加分项。PDF 输出里标签化结构也有助于生成带书签的电子书长文档跳转体验会顺畅很多。很多刚接触 Pretext 的人会问这不就是 XML 版本的 Markdown 吗从“用标记描述结构”这个角度看两者有思想上的相似之处。但 Markdown 为了写作方便弱化了很多结构边界比如脚注、术语表、索引、多级交叉引用这些在标准 Markdown 里并没有统一语法。Pretext 则把语义粒度拆得更细牺牲了一部分“零学习成本”换来的是复杂文档场景下更强的表达能力。2.2 一条命令输出多端HTML、PDF、EPUBPretext 给我印象最深的是它把“多格式输出”这件事做成了日常操作的一等公民。核心源文件是同一个 XML 文档通过命令行工具触发不同构建目标就能得到完全面向不同媒介的产物。整套构建流程大致是这样源文件先交给 XML 预处理器完成结构校验、交叉引用解析、编号自动分配再生成一个带完整导航信息的中间层。然后在 HTML 构建目标里使用 XSLT 把这些内容转换为一组静态网页在 PDF 构建目标里则把内容交给 LaTeX 引擎去排版EPUB 输出则会把内容打包成适用于移动阅读器的电子书格式。这里的关键点是目标格式之间的差异被引擎封装在了构建器内部。写作者不需要在源文件里塞一堆条件判断比如“如果是 PDF 就这样显示如果是网页就那样显示”。Pretext 规定了统一的结构入口剩下的分发逻辑由引擎自己处理。对我这种更关注内容本身的人来说这种设计省下了大量切换思维模式的时间。当然任何一种多格式输出方案都有细节差异需要面对。比如网页上数学公式靠 MathJax 在浏览器里动态渲染PDF 里数学公式则要借助 LaTeX 的数学排版能力网页上的图片可以随意放大PDF 里图片尺寸则需要考虑纸张规格和排版流。Pretext 的做法允许你在源文件里给同一张图片设置不同的显示描述但不强迫你为每个格式各维护一份文件。这是它比“复制粘贴三份文档再手动同步”要高一个维度的原因。2.3 和 LaTeX、Markdown、Word 放在一起看整理表格的时候我喜欢把这些工具按“标记方式、最适合场景、多格式输出、中文支持、学习成本”这几个维度拉出来对比。注意对比不是为了争谁最好而是为了确认 Pretext 最匹配什么样的人。工具标记方式最适合场景多格式输出中文支持学习成本LaTeX命令式标记学术论文、复杂数学排版强但需手动维护多种模板强需配置 CTeX 或 XeLaTeX高Markdown纯文本极简标记博客、README、短文中等依赖转换工具链好低Word富文本样式商务文档、流程表单弱版本间易漂移好低但维护成本高Pretext语义化 XML教材、长手册、在线课程强一处维护多端输出可配置需设置中文字体中高从这个表格能看出Pretext 和 LaTeX 在“多格式输出”和“严肃长文档”这两个方向上是同类竞争者但二者的标记哲学不同。LaTeX 写起来更像是在编程你在源文件里会直接看到\documentclass、\usepackage、\begin{center}这种命令Pretext 则尽量保持纯 XML 结构即便你不懂排版底层命令也能通过标签含义看懂内容结构。如果你的文档里有大量复杂公式又不想跳到 LaTeXPretext 是一个很自然的折中方案因为它生成 PDF 时依然会借助 LaTeX 的力量。3. 实操从零开始用 Pretext 排一篇文档3.1 环境准备Python、CLI 和必要的组件我这边使用的是当前比较常见的安装方式通过 Python 生态的 Pretext 命令行工具来构建项目。在开始之前先确认你的电脑上有 Python 3.9 或更新版本。虽然 Pretext 核心是 XML 处理但命令行工具本身是 Python 写的所以这一步跑不掉。我习惯先为项目建一个虚拟环境这样不容易污染全局环境也能避免不同项目依赖版本冲突。具体操作在终端里依次执行下面几条命令mkdir pretext-demo cd pretext-demo python -m venv .venv source .venv/bin/activate # Windows 下是 .venv\Scripts\activate pip install pretext安装完成后验证一下版本pretext --version如果能看到版本号说明核心 CLI 已经就绪。这里必须提醒一句如果你后面想生成 PDF还需要额外安装一个可用的 LaTeX 发行版。Windows 上推荐 TeX Live 或 MiKTeXmacOS 上则可以直接装 MacTeXLinux 发行版一般自带texlive包。这个依赖暂时没有也不影响先做 HTML 输出但一旦你点下“构建 PDF”按钮缺少 LaTeX 会立刻报错。3.2 创建项目官方示例其实是最好的起点Pretext 官方提供了一整套示例工程我建议不要从零手写项目结构而是先利用命令生成模板。以下命令在不同版本里可能略有差异但大体思路一致pretext new命令执行后它会问你项目名称和格式然后生成一个包含source、output、assets等目录的骨架。如果你用的版本没有pretext new命令也可以直接去官方仓库下载样例工程文件手动复制到本地。标准 Pretext 项目里核心文件是放在source目录下的我印象最深的两个文件是main.ptx和project.ptx。main.ptx是文档主体承载了你写的所有内容project.ptx则负责配置构建目标和方法相当于一份“说明书”告诉引擎生成 HTML 时用哪套模板、生成 PDF 时用哪个 LaTeX 编译器。这里有个经验不要一上来就修改太多配置。先打开模板里自带的示例章节跑通一次构建再逐步替换成自己的内容。这样出现问题时你能很容易判断是内容写法的问题还是配置层面的问题。新手最忌讳的是一步到位改完所有配置结果报错后根本不知道从哪里开始排查。3.3 写一个带标题、段落、数学公式的页面先从一个最简页面开始。我习惯把所有内容想成一颗树最外层是book或article下一层是chapter再下一层是section最小单位是段落、列表、图形这些叶子节点。下面是一个极简示例用来展示 Pretext 的书写方式pretext book chapter title第一次接触 Pretext/title section title为什么值得关注/title p 这是一个普通的段落。Pretext 关注的不是“这个段落应该用什么字体” 而是“这个段落处于哪个章节它的逻辑角色是什么”。 /p p 数学公式可以这样写mE mc^2/m。 如果你需要一段独立的居中公式可以写成 /p me \int_0^\infty e^{-x^2} dx \frac{\sqrt{\pi}}{2} /me /section /chapter /book /pretext注意m是行内数学标记me是独立展示的数学公式标记。Pretext 的数学语法基于 LaTeX 数学模式所以如果你会写 LaTeX 公式可以无缝迁移。这里要小心的一个陷阱是XML 本身对尖括号和与号敏感。如果正文里想写“小于号”或“与号”不能直接写或需要写成lt;和amp;否则解析器会报错。3.4 构建三端产物HTML、PDF、EPUB写完正文后就到了最有成就感的环节构建输出。在项目根目录执行pretext build html pretext build pdf pretext build epub三条命令分别对应网页、PDF 电子书、EPUB 电子书。构建成功后产出的文件都在output目录下。HTML 构建会生成一个静态网站直接双击index.html就能在浏览器里查看PDF 构建如果遇到缺失 LaTeX 依赖会有专门的中文提示EPUB 构建则生成一个适合导入阅读器的电子书文件。实际使用中我建议分阶段来。第一遍先只构建 HTML快速确认内容结构是否正常文字没有乱码标题层级是否完整。HTML 构建速度最快几十页的文档通常几秒内就能完成。确认内容没问题后再构建 PDF因为这个阶段需要启动 LaTeX 引擎第一次运行还可能要下载字体或宏包耗时明显长很多。如果只是改了某一个章节的文字没必要每次都全量构建。Pretext CLI 提供监听模式也就是持续观察源文件变化自动触发更新。用法大致是pretext watch html启动后本地会开一个开发服务器浏览器访问提示的地址你每保存一次源文件页面就自动刷新一次。这个功能对连续写作体验的提升非常明显我在写技术手册时基本离不开它。3.5 图片、引用和目录比想象中省心除了文字和公式文档里最常见的还有图片和交叉引用。Pretext 里插入图片的方式很直接先把图片文件放进assets/images或类似目录然后通过image标签引用。举例figure xml:idfig-architecture image sourcearchitecture.png width80%/ caption系统整体架构图/caption /figurexml:id在这里特别重要它是交叉引用的锚点。我在正文里想提到这张图只需要写p系统整体架构如图xref reffig-architecture/所示。/p引擎在构建时会自动把xref里的编号替换成实际图号在 HTML 中它会变成一个可点击的锚点链接在 PDF 中则会显示成“图 3-1”并且在点击时跳转。这种自动编号功能对长篇技术文档来说省掉了大量人工维护成本。目录同理你不需要手动维护“目 录”页只要章节标签写得完整引擎会按照文档结构自动生成目录树。4. 实战中的常见问题与排查技巧4.1 中文环境下PDF 输出变成方块或乱码这是中文用户最容易遇到的第一个坑。核心原因在于Pretext 生成 PDF 时默认依赖的 LaTeX 引擎或字体配置不一定支持中文。解决方法无非两条路让 LaTeX 认出中文字体或者换用支持中文的编译方式。我目前的经验是在project.ptx中把 PDF 构建方法明确设置为 XeLaTeX因为 XeLaTeX 可以直接调用系统字体对中文支持更友好。同时还需要在模板配置里指定中文字体比如“Noto Sans CJK”或者“Source Han Serif”。如果用的发行版是 TeX Live也可以安装ctex宏包并在序言区加入\usepackage{ctex}这样中文排版基本不会再出幺蛾子。初学时如果不想折腾这些底层配置最简单的办法是先找到一个已经跑通中文的官方示例把字体相关的配置文件原样复制过来再改标题和内容。这个办法不优雅但胜在安全。等对 Pretext 熟悉之后再按照自己团队的字体现状精细调整也不迟。4.2 数学公式和特殊符号渲染不一致数学公式在 HTML 和 PDF 两个目标里走的是两条不同技术路线。HTML 端使用 MathJax在浏览器里渲染PDF 端使用 LaTeX 编译。绝大多数常规公式两边都能保持一致但个别自定义宏包或特殊符号可能出现网页端正常、PDF 端报错的情况。我的排查思路通常是把公式拆小一点点缩小范围。先写一个最简单的公式就像\(xy\)那样分别构建 HTML 和 PDF确认环境本身没问题。然后逐步加上运算符、上下标、分类符看看是哪一步破坏了构建。大部分报错都是因为在源文件里写了 XML 不认的字符比如和。如果确实需要写不等式记得用转义写法lt;和gt;。另一个经验是不要直接从 Word 或网页里复制公式对象进来。那些对象往往带着私有格式粘贴到 XML 中要么乱码要么变成一堆没用的元数据。正确做法是只保留公式的 LaTeX 文本再把它放入m或me标签内。哪怕一开始觉得手写 LaTeX 慢也比从外部粘贴再调试半天要快得多。4.3 构建报错XSLT 与 Saxon 的坑Pretext 的 HTML 构建底层依赖 XSLT 转换而 XSLT 转换工具需要 Java 运行环境。如果你在构建 HTML 时看到类似“找不到 Saxon 处理器”或“Java 未安装”的提示先去检查 JDK 是否安装并正确配置了JAVA_HOME环境变量。安装 OpenJDK 后需要重启终端窗口使环境变量生效。某些 Linux 发行版还会遇到 PATH 里没有包含新安装 Java 路径的情况可以手动执行export JAVA_HOME/usr/lib/jvm/...临时设置。这些都不是 Pretext 本身的问题而是本地环境不完整导致的。遇到类似报错时不要急着卸载重装 Pretext先看日志里是否提到依赖缺失。还有一个隐蔽问题如果源 XML 文件缺少根元素或出现了重复的xml:id预处理阶段就会提前失败。这类错误在报错信息里往往不显眼但只要你仔细检查一遍 XML 标签闭合以及所有xml:id是否全局唯一多半就能解决。我的习惯是用带 XML 校验功能的编辑器写源文件比如 VS Code 安装 XML 插件能在我保存前就发现一半以上低级错误。4.4 图片路径、目录组织与多文件协作Pretext 是语义化结构所以天然支持把一个大文档拆分成多个文件。你可以把每个章节放在独立的 XML 文件里然后用xi:include或include机制在根文件中引用。这种方式对多人协作很有帮助每个人只需要维护自己负责的章节合并冲突的概率小很多。不过拆分文件也带来两个需要注意的点。一个是图片路径源文件里写的相对路径是相对于项目根目录而不是相对于当前章节文件所在目录。如果图片分散在不同文件夹我的建议是在项目根层级统一用一个assets目录管理所有二进制资源这样无论章节文件在哪里引用路径都很好维护。另一个是唯一标识所有xml:id在多文件环境下仍然是全局命名空间所以不能出现两个章节里使用同一个锚点 id否则交叉引用会乱套。如果是多人协作强烈建议给标签使用规范定一个简单文档标题怎么分、图注怎么写、交叉引用怎么命名、图片命名规则是什么。没有约定的话同一套文档里会出现风格五花八门的标签写法虽然不至于导致构建失败但后续维护时会让人非常头疼。Pretext 给了结构自由度团队就需要用规则去约束这份自由。4.5 性能问题大型文档构建慢怎么办大型书籍级文档动辄几百个章节、上千张图全量构建 PDF 确实可能耗时数分钟。每次改一个字都要重新编译全本文檔会非常煎熬。我的做法是日常写作阶段只维护 HTML 预览开启监听模式保存后几乎秒级刷新。只有在提交版本或需要交付印刷稿时才去构建 PDF。如果你已经明确只需要其中一章的 PDF也可以考虑临时把源文件根节点改成只包含该章节的片段构建完成后再改回来。这个方法虽然有一点“手动味”但在紧急改稿时非常管用比守着完整构建好几分钟舒服得多。另外Pretext 的构建过程会生成缓存重复构建时部分工作会被跳过。不要每次构建前都手动删除output目录尤其不要删除隐藏的状态文件。除非你遇到了“改了源码但输出没变”的诡异问题才值得尝试完全清理后重新构建。正常情况下信任增量构建机制能帮你节省大量时间。5. 一些值得去试的场景前面这些技术细节其实核心都是在说一件事Pretext 把长文档的“结构管理”做得很扎实。我个人的实际感受是它最适合那些内容会长期演进、并且需要多种输出渠道的场景。举几个我亲测体验不错的例子。第一类是在线课程网站。教师只需要维护一套源文件既能在 Web 端生成课程主页还能同步生成 PDF 讲义和 EPUB 电子版。学生端看到的网页版里有可点击的交叉引用、自动生成的目录印刷版的讲义又保持了同类章节结构。对于经常更新课程内容的高校教师来说这种“一处修改、多端同步”的工作流比每学期重新排版一遍 Word 要省力太多。第二类是团队知识库。企业里最怕的不是文档少而是文档散。同一个操作流程可能在培训手册、内部 Wiki、客户文档里各出现一次内容还不一致。把这些内容统一放入 Pretext再分别生成内部 Wiki 页和客户 PDF至少能保证信息来源是同一个版本。如果配上 Git 管理每一次内容变更都有历史记录出了责任问题也能追溯。第三类是开源项目文档。项目维护者通常不想花太多精力维护文档站但用户又需要一份排版不错的 PDF 手册。Pretext 的静态 HTML 输出可以直接托管到任何静态站点服务上构建过程还可以写进 CI/CD 流程每次代码合并后自动从源文件生成最新文档站和 PDF 附件。这一点对开发者友好因为我们最讨厌的就是“本地可以线上没更新”的文档同步悲剧。当然Pretext 也有它的学习成本。如果你完全不会 XML前两三天肯定会觉得标签有点繁琐。但我建议你先别急着定义“麻烦”先用官方示例跑通全流程再把一套自己章节内容迁移进去试一次。等你真正体验到“同一条引用在网页和 PDF 里自动指向同一张图”那种畅快感后大概率会回不去 Word 手工维护目录和编号的日子。最后再分享一个小技巧在项目文档模板里固定一套自己的标签规范和文件目录约定哪怕只有两三个人的小团队也会因此受益。Pretext 的引擎做得越聪明你就越应该在内容组织上多花一点点心思这样它的能力才能真正为你所用。
Pretext：用语义化写作搞定长文档多格式排版引擎
提起文本排版引擎很多人第一时间想到的是 LaTeX、Pandoc或者 Word 里那套让人又爱又恨的样式系统。今天我想聊的是一个相对小众但非常值得关注的项目Pretext。简单说Pretext 是一个面向结构化长文档的文本排版引擎作者只负责写内容和语义结构剩下的 HTML、PDF、EPUB 输出全部交给引擎去处理。它特别适合技术手册、在线课程、教材这类“一次编写、多处发布”的场景也适合那些已经被 Markdown 和 Word 折腾到崩溃的内容团队。如果你正在找一条能同时兼顾印刷质量、网页体验和长期维护的路Pretext 值得你花一个周末认真试一试。1. Pretext 到底解决什么问题1.1 被标记语言“框住”的作者们先说说我自己踩过的坑。早几年写博客的时候我一直用 Markdown轻快是真轻快不需要学习什么炫酷语法打开编辑器就能写。可一旦文档规模变大问题就接踵而至脚注还能忍交叉引用就有点别扭到了“给同一个术语生成索引”“根据文章结构变化自动更新目录”“同一份内容既要出网页版又要出排版精美的 PDF 讲义”这些需求时Markdown 基本就力不从心了。于是很多人转向 LaTeX。LaTeX 的排版质量确实没话说尤其是学术论文、数学公式、复杂表格几乎是无敌的存在。但它的代价同样明显语法门槛高光是把字体、页面边距、标题层级这些“样式细节”调明白就足以劝退一批怀抱写作理想的人。更关键的是LaTeX 作者往往在写内容的同时还要分心去维护一堆排版命令内容与表现搅在一起后期改版时牵一发而动全身。Word 则是另一个极端。打开即写所见即所得大部分办公场景都能对付。但长文档一到多人协作就变灾难样式漂移、目录不同步、页码错乱、图注编号失踪再加上不同 Office 版本之间兼容性差异文档越改越像一个装满雷的地下室谁都不敢轻易碰。Pretext 的切入点是为什么不把“内容该说些什么”和“内容看起来什么样”彻底拆开作者只标记“这是一个章节标题”“这是一段警告”“这是一个引用来源”而不是直接指定“这里是黑体三号居中”。排版引擎拿到语义化标记后再根据你选择的目标格式去渲染成漂亮的页面或严谨的印刷稿。这种思路并不算激进DocBook、DITA 等老牌方案早就验证过但 Pretext 在数学排版、Web 输出、课程资料场景上做得格外顺手。1.2 Pretext 的定位给长文档和结构化内容用的排版引擎如果要用一句话概括Pretext 是一个“以 XML 语义标记为源文件面向书籍、教材、技术文档的文本排版引擎”。它不像 Word 那样让你看到最终效果也不像 Markdown 那样让你用最少的符号完成轻量排版。它更像是一套工厂流水线输入是结构清晰的源文件输出是多种终端产品。我更愿意称它为“结构化作者的生产工具”。因为它的根元素通常是book、article、webpage这类语义化容器内部由chapter、section、p、figure、xref等结构标签组成。作者写的不是“某一段用什么格式显示”而是“这一段在小节结构中的位置是什么、和哪些内容存在引用关系”。这种定位带来一个很实际的好处改版效率极高。我可以先给团队做 HTML 版本文档站让读者在浏览器里直接阅读再用同一套源文件编译 PDF 版讲义投递给印刷厂。传统工作流里这两套产物往往需要人工同步改了网页忘了 PDF 是常态。Pretext 里它们只是同一次构建的不同目标内容永远只有一份。当然Pretext 不是万能钥匙。如果只是写几百字的随手笔记或者需要高频改动表格样式它的上手成本未必划算。它最舒服的领域是内容量大、结构稳定、需要长期维护和多次发布的场景。我在实际项目中见过的典型使用人群包括大学老师教材与课件同步、开源项目维护者在线文档与 PDF 手册同步、制造业企业技术规范与培训材料同步还有做内部知识库的团队。2. 拆解 Pretext 的核心设计怎样的排版引擎才值得关注2.1 语义化写作内容与样式彻底分离“语义化写作”这个词听起来很抽象我用一个生活化类比解释一下。小时候玩积木每一块积木都有自己的形状有的是长条有的是方块有的是拱门。你可以用同样一堆积木搭出欧洲城堡也可以搭出中式庭院。积木本身没有变成城堡或庭院是搭建方式和外部装饰决定了最终风格。Pretext 的源文件就是那堆积木。你用title声明一个标题用p声明一个段落用figure声明一张图。至于这个标题是显示成黑体还是宋体段落之间要不要缩进图片在页面上是居中还是靠边那是排版引擎和样式表的事不归源文件管。这种分离带来的影响是深远的。首先目录和交叉引用可以自动生成。因为排版引擎知道哪些标签属于标题层级它可以在预处理阶段数一下结构然后自动生成完整的目录。当我在第二章里插入一个“见第三章第四节”的引用时不需要手写编号只要写xref refsome-section-id/最终生成的每个格式里都会自动填入正确的编号。其次无障碍可访问性更好。HTML 输出里section、nav、figure这些元素能正确映射到浏览器的语义结构屏幕阅读器可以更准确地理解内容层次。这对做公开教学网站或者政府类信息服务的人来说是一项隐形的加分项。PDF 输出里标签化结构也有助于生成带书签的电子书长文档跳转体验会顺畅很多。很多刚接触 Pretext 的人会问这不就是 XML 版本的 Markdown 吗从“用标记描述结构”这个角度看两者有思想上的相似之处。但 Markdown 为了写作方便弱化了很多结构边界比如脚注、术语表、索引、多级交叉引用这些在标准 Markdown 里并没有统一语法。Pretext 则把语义粒度拆得更细牺牲了一部分“零学习成本”换来的是复杂文档场景下更强的表达能力。2.2 一条命令输出多端HTML、PDF、EPUBPretext 给我印象最深的是它把“多格式输出”这件事做成了日常操作的一等公民。核心源文件是同一个 XML 文档通过命令行工具触发不同构建目标就能得到完全面向不同媒介的产物。整套构建流程大致是这样源文件先交给 XML 预处理器完成结构校验、交叉引用解析、编号自动分配再生成一个带完整导航信息的中间层。然后在 HTML 构建目标里使用 XSLT 把这些内容转换为一组静态网页在 PDF 构建目标里则把内容交给 LaTeX 引擎去排版EPUB 输出则会把内容打包成适用于移动阅读器的电子书格式。这里的关键点是目标格式之间的差异被引擎封装在了构建器内部。写作者不需要在源文件里塞一堆条件判断比如“如果是 PDF 就这样显示如果是网页就那样显示”。Pretext 规定了统一的结构入口剩下的分发逻辑由引擎自己处理。对我这种更关注内容本身的人来说这种设计省下了大量切换思维模式的时间。当然任何一种多格式输出方案都有细节差异需要面对。比如网页上数学公式靠 MathJax 在浏览器里动态渲染PDF 里数学公式则要借助 LaTeX 的数学排版能力网页上的图片可以随意放大PDF 里图片尺寸则需要考虑纸张规格和排版流。Pretext 的做法允许你在源文件里给同一张图片设置不同的显示描述但不强迫你为每个格式各维护一份文件。这是它比“复制粘贴三份文档再手动同步”要高一个维度的原因。2.3 和 LaTeX、Markdown、Word 放在一起看整理表格的时候我喜欢把这些工具按“标记方式、最适合场景、多格式输出、中文支持、学习成本”这几个维度拉出来对比。注意对比不是为了争谁最好而是为了确认 Pretext 最匹配什么样的人。工具标记方式最适合场景多格式输出中文支持学习成本LaTeX命令式标记学术论文、复杂数学排版强但需手动维护多种模板强需配置 CTeX 或 XeLaTeX高Markdown纯文本极简标记博客、README、短文中等依赖转换工具链好低Word富文本样式商务文档、流程表单弱版本间易漂移好低但维护成本高Pretext语义化 XML教材、长手册、在线课程强一处维护多端输出可配置需设置中文字体中高从这个表格能看出Pretext 和 LaTeX 在“多格式输出”和“严肃长文档”这两个方向上是同类竞争者但二者的标记哲学不同。LaTeX 写起来更像是在编程你在源文件里会直接看到\documentclass、\usepackage、\begin{center}这种命令Pretext 则尽量保持纯 XML 结构即便你不懂排版底层命令也能通过标签含义看懂内容结构。如果你的文档里有大量复杂公式又不想跳到 LaTeXPretext 是一个很自然的折中方案因为它生成 PDF 时依然会借助 LaTeX 的力量。3. 实操从零开始用 Pretext 排一篇文档3.1 环境准备Python、CLI 和必要的组件我这边使用的是当前比较常见的安装方式通过 Python 生态的 Pretext 命令行工具来构建项目。在开始之前先确认你的电脑上有 Python 3.9 或更新版本。虽然 Pretext 核心是 XML 处理但命令行工具本身是 Python 写的所以这一步跑不掉。我习惯先为项目建一个虚拟环境这样不容易污染全局环境也能避免不同项目依赖版本冲突。具体操作在终端里依次执行下面几条命令mkdir pretext-demo cd pretext-demo python -m venv .venv source .venv/bin/activate # Windows 下是 .venv\Scripts\activate pip install pretext安装完成后验证一下版本pretext --version如果能看到版本号说明核心 CLI 已经就绪。这里必须提醒一句如果你后面想生成 PDF还需要额外安装一个可用的 LaTeX 发行版。Windows 上推荐 TeX Live 或 MiKTeXmacOS 上则可以直接装 MacTeXLinux 发行版一般自带texlive包。这个依赖暂时没有也不影响先做 HTML 输出但一旦你点下“构建 PDF”按钮缺少 LaTeX 会立刻报错。3.2 创建项目官方示例其实是最好的起点Pretext 官方提供了一整套示例工程我建议不要从零手写项目结构而是先利用命令生成模板。以下命令在不同版本里可能略有差异但大体思路一致pretext new命令执行后它会问你项目名称和格式然后生成一个包含source、output、assets等目录的骨架。如果你用的版本没有pretext new命令也可以直接去官方仓库下载样例工程文件手动复制到本地。标准 Pretext 项目里核心文件是放在source目录下的我印象最深的两个文件是main.ptx和project.ptx。main.ptx是文档主体承载了你写的所有内容project.ptx则负责配置构建目标和方法相当于一份“说明书”告诉引擎生成 HTML 时用哪套模板、生成 PDF 时用哪个 LaTeX 编译器。这里有个经验不要一上来就修改太多配置。先打开模板里自带的示例章节跑通一次构建再逐步替换成自己的内容。这样出现问题时你能很容易判断是内容写法的问题还是配置层面的问题。新手最忌讳的是一步到位改完所有配置结果报错后根本不知道从哪里开始排查。3.3 写一个带标题、段落、数学公式的页面先从一个最简页面开始。我习惯把所有内容想成一颗树最外层是book或article下一层是chapter再下一层是section最小单位是段落、列表、图形这些叶子节点。下面是一个极简示例用来展示 Pretext 的书写方式pretext book chapter title第一次接触 Pretext/title section title为什么值得关注/title p 这是一个普通的段落。Pretext 关注的不是“这个段落应该用什么字体” 而是“这个段落处于哪个章节它的逻辑角色是什么”。 /p p 数学公式可以这样写mE mc^2/m。 如果你需要一段独立的居中公式可以写成 /p me \int_0^\infty e^{-x^2} dx \frac{\sqrt{\pi}}{2} /me /section /chapter /book /pretext注意m是行内数学标记me是独立展示的数学公式标记。Pretext 的数学语法基于 LaTeX 数学模式所以如果你会写 LaTeX 公式可以无缝迁移。这里要小心的一个陷阱是XML 本身对尖括号和与号敏感。如果正文里想写“小于号”或“与号”不能直接写或需要写成lt;和amp;否则解析器会报错。3.4 构建三端产物HTML、PDF、EPUB写完正文后就到了最有成就感的环节构建输出。在项目根目录执行pretext build html pretext build pdf pretext build epub三条命令分别对应网页、PDF 电子书、EPUB 电子书。构建成功后产出的文件都在output目录下。HTML 构建会生成一个静态网站直接双击index.html就能在浏览器里查看PDF 构建如果遇到缺失 LaTeX 依赖会有专门的中文提示EPUB 构建则生成一个适合导入阅读器的电子书文件。实际使用中我建议分阶段来。第一遍先只构建 HTML快速确认内容结构是否正常文字没有乱码标题层级是否完整。HTML 构建速度最快几十页的文档通常几秒内就能完成。确认内容没问题后再构建 PDF因为这个阶段需要启动 LaTeX 引擎第一次运行还可能要下载字体或宏包耗时明显长很多。如果只是改了某一个章节的文字没必要每次都全量构建。Pretext CLI 提供监听模式也就是持续观察源文件变化自动触发更新。用法大致是pretext watch html启动后本地会开一个开发服务器浏览器访问提示的地址你每保存一次源文件页面就自动刷新一次。这个功能对连续写作体验的提升非常明显我在写技术手册时基本离不开它。3.5 图片、引用和目录比想象中省心除了文字和公式文档里最常见的还有图片和交叉引用。Pretext 里插入图片的方式很直接先把图片文件放进assets/images或类似目录然后通过image标签引用。举例figure xml:idfig-architecture image sourcearchitecture.png width80%/ caption系统整体架构图/caption /figurexml:id在这里特别重要它是交叉引用的锚点。我在正文里想提到这张图只需要写p系统整体架构如图xref reffig-architecture/所示。/p引擎在构建时会自动把xref里的编号替换成实际图号在 HTML 中它会变成一个可点击的锚点链接在 PDF 中则会显示成“图 3-1”并且在点击时跳转。这种自动编号功能对长篇技术文档来说省掉了大量人工维护成本。目录同理你不需要手动维护“目 录”页只要章节标签写得完整引擎会按照文档结构自动生成目录树。4. 实战中的常见问题与排查技巧4.1 中文环境下PDF 输出变成方块或乱码这是中文用户最容易遇到的第一个坑。核心原因在于Pretext 生成 PDF 时默认依赖的 LaTeX 引擎或字体配置不一定支持中文。解决方法无非两条路让 LaTeX 认出中文字体或者换用支持中文的编译方式。我目前的经验是在project.ptx中把 PDF 构建方法明确设置为 XeLaTeX因为 XeLaTeX 可以直接调用系统字体对中文支持更友好。同时还需要在模板配置里指定中文字体比如“Noto Sans CJK”或者“Source Han Serif”。如果用的发行版是 TeX Live也可以安装ctex宏包并在序言区加入\usepackage{ctex}这样中文排版基本不会再出幺蛾子。初学时如果不想折腾这些底层配置最简单的办法是先找到一个已经跑通中文的官方示例把字体相关的配置文件原样复制过来再改标题和内容。这个办法不优雅但胜在安全。等对 Pretext 熟悉之后再按照自己团队的字体现状精细调整也不迟。4.2 数学公式和特殊符号渲染不一致数学公式在 HTML 和 PDF 两个目标里走的是两条不同技术路线。HTML 端使用 MathJax在浏览器里渲染PDF 端使用 LaTeX 编译。绝大多数常规公式两边都能保持一致但个别自定义宏包或特殊符号可能出现网页端正常、PDF 端报错的情况。我的排查思路通常是把公式拆小一点点缩小范围。先写一个最简单的公式就像\(xy\)那样分别构建 HTML 和 PDF确认环境本身没问题。然后逐步加上运算符、上下标、分类符看看是哪一步破坏了构建。大部分报错都是因为在源文件里写了 XML 不认的字符比如和。如果确实需要写不等式记得用转义写法lt;和gt;。另一个经验是不要直接从 Word 或网页里复制公式对象进来。那些对象往往带着私有格式粘贴到 XML 中要么乱码要么变成一堆没用的元数据。正确做法是只保留公式的 LaTeX 文本再把它放入m或me标签内。哪怕一开始觉得手写 LaTeX 慢也比从外部粘贴再调试半天要快得多。4.3 构建报错XSLT 与 Saxon 的坑Pretext 的 HTML 构建底层依赖 XSLT 转换而 XSLT 转换工具需要 Java 运行环境。如果你在构建 HTML 时看到类似“找不到 Saxon 处理器”或“Java 未安装”的提示先去检查 JDK 是否安装并正确配置了JAVA_HOME环境变量。安装 OpenJDK 后需要重启终端窗口使环境变量生效。某些 Linux 发行版还会遇到 PATH 里没有包含新安装 Java 路径的情况可以手动执行export JAVA_HOME/usr/lib/jvm/...临时设置。这些都不是 Pretext 本身的问题而是本地环境不完整导致的。遇到类似报错时不要急着卸载重装 Pretext先看日志里是否提到依赖缺失。还有一个隐蔽问题如果源 XML 文件缺少根元素或出现了重复的xml:id预处理阶段就会提前失败。这类错误在报错信息里往往不显眼但只要你仔细检查一遍 XML 标签闭合以及所有xml:id是否全局唯一多半就能解决。我的习惯是用带 XML 校验功能的编辑器写源文件比如 VS Code 安装 XML 插件能在我保存前就发现一半以上低级错误。4.4 图片路径、目录组织与多文件协作Pretext 是语义化结构所以天然支持把一个大文档拆分成多个文件。你可以把每个章节放在独立的 XML 文件里然后用xi:include或include机制在根文件中引用。这种方式对多人协作很有帮助每个人只需要维护自己负责的章节合并冲突的概率小很多。不过拆分文件也带来两个需要注意的点。一个是图片路径源文件里写的相对路径是相对于项目根目录而不是相对于当前章节文件所在目录。如果图片分散在不同文件夹我的建议是在项目根层级统一用一个assets目录管理所有二进制资源这样无论章节文件在哪里引用路径都很好维护。另一个是唯一标识所有xml:id在多文件环境下仍然是全局命名空间所以不能出现两个章节里使用同一个锚点 id否则交叉引用会乱套。如果是多人协作强烈建议给标签使用规范定一个简单文档标题怎么分、图注怎么写、交叉引用怎么命名、图片命名规则是什么。没有约定的话同一套文档里会出现风格五花八门的标签写法虽然不至于导致构建失败但后续维护时会让人非常头疼。Pretext 给了结构自由度团队就需要用规则去约束这份自由。4.5 性能问题大型文档构建慢怎么办大型书籍级文档动辄几百个章节、上千张图全量构建 PDF 确实可能耗时数分钟。每次改一个字都要重新编译全本文檔会非常煎熬。我的做法是日常写作阶段只维护 HTML 预览开启监听模式保存后几乎秒级刷新。只有在提交版本或需要交付印刷稿时才去构建 PDF。如果你已经明确只需要其中一章的 PDF也可以考虑临时把源文件根节点改成只包含该章节的片段构建完成后再改回来。这个方法虽然有一点“手动味”但在紧急改稿时非常管用比守着完整构建好几分钟舒服得多。另外Pretext 的构建过程会生成缓存重复构建时部分工作会被跳过。不要每次构建前都手动删除output目录尤其不要删除隐藏的状态文件。除非你遇到了“改了源码但输出没变”的诡异问题才值得尝试完全清理后重新构建。正常情况下信任增量构建机制能帮你节省大量时间。5. 一些值得去试的场景前面这些技术细节其实核心都是在说一件事Pretext 把长文档的“结构管理”做得很扎实。我个人的实际感受是它最适合那些内容会长期演进、并且需要多种输出渠道的场景。举几个我亲测体验不错的例子。第一类是在线课程网站。教师只需要维护一套源文件既能在 Web 端生成课程主页还能同步生成 PDF 讲义和 EPUB 电子版。学生端看到的网页版里有可点击的交叉引用、自动生成的目录印刷版的讲义又保持了同类章节结构。对于经常更新课程内容的高校教师来说这种“一处修改、多端同步”的工作流比每学期重新排版一遍 Word 要省力太多。第二类是团队知识库。企业里最怕的不是文档少而是文档散。同一个操作流程可能在培训手册、内部 Wiki、客户文档里各出现一次内容还不一致。把这些内容统一放入 Pretext再分别生成内部 Wiki 页和客户 PDF至少能保证信息来源是同一个版本。如果配上 Git 管理每一次内容变更都有历史记录出了责任问题也能追溯。第三类是开源项目文档。项目维护者通常不想花太多精力维护文档站但用户又需要一份排版不错的 PDF 手册。Pretext 的静态 HTML 输出可以直接托管到任何静态站点服务上构建过程还可以写进 CI/CD 流程每次代码合并后自动从源文件生成最新文档站和 PDF 附件。这一点对开发者友好因为我们最讨厌的就是“本地可以线上没更新”的文档同步悲剧。当然Pretext 也有它的学习成本。如果你完全不会 XML前两三天肯定会觉得标签有点繁琐。但我建议你先别急着定义“麻烦”先用官方示例跑通全流程再把一套自己章节内容迁移进去试一次。等你真正体验到“同一条引用在网页和 PDF 里自动指向同一张图”那种畅快感后大概率会回不去 Word 手工维护目录和编号的日子。最后再分享一个小技巧在项目文档模板里固定一套自己的标签规范和文件目录约定哪怕只有两三个人的小团队也会因此受益。Pretext 的引擎做得越聪明你就越应该在内容组织上多花一点点心思这样它的能力才能真正为你所用。