1. 看了十几年 LaTeX我为什么开始留意 Pretext最早知道 Pretext现在官方拼写是 PreTeXt但很多文章和标题里还保留 Pretext 的写法指的都是同一条文本排版引擎是在找开放教材的时候。当时我手头有个挺实际的痛点用 LaTeX 写了一本两百多页的数学讲义排版质量没话说可是当我想同时产出网页版、打印版和电子书时一份.tex源码几乎没法复用。网页版要么切成 PDF 挂上去要么用tex4ht这种老牌转换工具搞出样式很粗糙的 HTML。那一刻我突然意识到LaTeX 解决的是渲染得多好看没有解决内容本身怎么组织。PreTeXt 这个文本排版引擎吸引我是因为它走了一条跟 LaTeX 完全不同的路你写的是带语义的 XML 文档告诉引擎这是一个问题这是一个提示这是一个交叉引用再由引擎去生成 PDF、HTML、EPUB 甚至盲文版本。听起来有点抽象实际操作之后你会发现它真的是奔着写一本教材这个场景去的。1.1 排版引擎真正稀缺的不是渲染而是结构市面上常用的排版方案其实各有各的妥协。LaTeX 的好处是输出质量高、数学排版无出其右但它的源码把内容和样式混在一起\textbf{}、\section{}是在描述用什么样子展示不是描述这一段在文章里是什么角色。Word 让你所见即所得可一旦文档长了标题层级靠手调格式交叉引用靠手动编号改一次章节顺序就要老命。Markdown 写起来轻快但到了学术级公式、习题、答案分离、跨章节引用这些场景基本不够用。PreTeXt 的出发点恰恰是先解决结构这个问题。它要求你用title、paragraph、exercise、solution这类语义化标签来标记内容而不是直接写这行字要加粗或者这里是二级标题。这种设计最大的好处是一切后续的排版行为都变成了根据结构做决定而不是解析一堆格式命令去猜作者的意图。打个比方LaTeX 像是你把菜洗好切好递给厨师厨师按他的经验炒PreTeXt 像是你给了一套标准化的食材分类每家餐厅可以按自己的菜谱做出口味不同的菜但食材意识是统一的。所以我现在评判一个排版工具第一反应不是看它渲染效果多花哨而是看它有没有把我写的这东西是什么和这东西最后长什么样拆开。PreTeXt 是拆得最彻底的一个。1.2 MathBook XML 到 PreTeXt一个为教材而生的项目PreTeXt 不是凭空冒出来的。它的前身叫 MathBook XML主要用于编写开源数学教材最有名的例子就是 Rob Beezer 那本A First Course in Linear Algebra。后来项目更名 PreTeXt范围也从单纯数学扩展到物理、计算机等理工科教材。可以说这个文本排版引擎是在一本又一本真实出版的教材里捶打出来的而不是实验室里的玩具。这一点对我来说很重要。因为一个排版工具好不好用不能只看示例文档做得漂不漂亮要看它在几百页的长文档、几十位协作者、同时维护网页版和打印版的真实压力下撑不撑得住。PreTeXt 在这类场景里有大量实战积累自动编号、自动交叉引用、习题答案分离、无障碍阅读、多格式输出这些都是教材作者天天要面对的问题。我当初正是看了几本用 PreTeXt 写出来的成品教材才决定认真试一下而不是只对着文档空想。2. Pretext 到底改了什么从 Markdown/Markup 到语义化写作刚开始接触 PreTeXt 的人最不习惯的一点就是为什么文档非得写成 XML。说实话我一开始也有这个疑问觉得 XML 写起来比 Markdown 啰嗦多了。但等我把一个简单章节从编写到编译走完一遍就明白了PreTeXt 的 XML 节点不是排版指令它们是内容类型的定义。2.1 一次编写四个出口PreTeXt 的构建管线本质上是一个变换系统你的源文件main.ptx是唯一的事实来源pretext build命令负责把它转换到目标格式。pretext build html生成一个带交互的 HTML 站点数学公式用 MathJax 或 KaTeX 渲染。pretext build pdf先生成临时 LaTeX 文件再调用xelatex或lualatex编译成 PDF。pretext build epub生成电子书适合放到阅读器里。pretext build braille生成盲文版本这个在无障碍出版圈很受重视。这个设计意味着你不需要维护四份不同格式的文档只需要改main.ptx然后按需构建。当时让我眼前一亮的是它生成的 HTML 不是一张图片或者一整页静态文本而是真正可选中、可复制、可检索的文本内容公式也是可访问的。对于教学场景来说学生可以在手机上直接打开网页版阅读体验比抱着一个 PDF 舒服太多。2.2 语义标签让文档会说话用 PreTeXt 写文档标记语言的粒度比 Markdown 细很多。行内公式用m独立公式用me段落是p章节标题是title习题是exercise习题下面还能嵌套hint、answer、solution三种不同性质的块。举个很直观的例子。LaTeX 里你写习题答案通常是这样\begin{exercise} 请证明勾股定理。 \end{exercise} \begin{solution} 略。 \end{solution}在 PreTeXt 里这样写exercise xml:idexercise-pythagorean statement p请证明勾股定理。/p /statement hint p尝试构造一个以斜边为边长的正方形。/p /hint answer p略。/p /answer solution p此处给出完整证明。/p /solution /exercise区别在哪在 HTML 输出里提示、答案、解答默认不会全部摊开而是折叠成可交互的 Knowl读者点击才展开在 PDF 输出里它们又可以按出版需求集中排到书末或者直接跟在习题后面。关键是你不需要在源码里来回调整这个怎么呈现的决定权交给了构建配置而不是写文档时的手工劳动。2.3 与 LaTeX 的关系不是替代而是封装很多人第一次听说 PreTeXt 时都会问它不是又搞了一套 LaTeX 吗其实不是。PreTeXt 的 PDF 后端依赖 LaTeX它内部会把语义化标签转换成 LaTeX 代码再交给引擎编译。所以它不是一个和 LaTeX 对着干的工具更像是在 LaTeX 外层加了一个语义层。作者不需要在源文件里关心\usepackage和宏包冲突那些都沉淀到 publication 配置里了。这个设计有得有失。好的方面是写文档的人不需要记住复杂的 LaTeX 命令只需要了解二三十个 XML 标签就能开始不熟悉的方面是如果你想用某个冷门的 LaTeX 宏包PreTeXt 的封装层支持不了你只能回到\usepackage层面的 hack。我的判断是对教材、讲义、开放课程这类有明确结构的长文档这个代价可以接受对需要高度定制排版效果的用户还是直接用 LaTeX 更划算。3. 半小时搭出一个能编译的 Pretext 项目说了这么多理念不如直接动手。这一节我用一个最简项目从零到一跑通 HTML 和 PDF 输出。整个过程不涉及复杂配置只要你按步骤来一般十几分钟就能看到产物。3.1 环境准备和安装PreTeXt 的 CLI 是用 Python 写的安装其实很简单python3 -m pip install pretext装完检查一下版本pretext --version如果只想构建 HTML有 Python 就够了不需要装 LaTeX。如果还想生成 PDF就需要一个可用的 TeX 发行版Linux 装 TeX LivemacOS 装 MacTeXWindows 用 MiKTeX 或 TeX Live 都可以。另外PDF 构建默认走xelatex所以得保证 TeX 发行版里带了 XeTeX 引擎。我用的是 TeX Live 的完整版暂时没遇到缺模块的问题如果你是精简安装可能要按报错提示补几个宏包。提示如果你对系统环境不太放心可以先跑pretext build html完全不依赖 LaTeX。等 HTML 摸熟了再处理 PDF 那一套。3.2 手写一个最小 main.ptx 并编译PreTeXt 的项目结构很清晰。通常你会有一个source目录里面放着核心源文件main.ptx。用 CLI 也可以直接生成骨架pretext new demo如果命令可用它会帮你建好目录和默认配置文件。老版本可能没有pretext new那就手动创建source/main.ptx也是一个可行的路子。下面是一个最小的source/main.ptx?xml version1.0 encodingUTF-8? pretext xmlns:xihttp://www.w3.org/2001/XInclude book xml:iddemo-book title我的第一本 PreTeXt 讲义/title chapter xml:idchapter-intro title一个最简单的章节/title section xml:idsec-hello title你好PreTeXt/title p 这篇文章里写了行内公式 ma^2 b^2/m 也写了独立公式 mex^2 y^2 z^2./me /p /section /chapter /book /pretext保存后在项目根目录执行pretext build html产物会生成在output/html目录打开里面的index.html就能看到效果。公式有没有渲染成功是这个最小项目是否跑通的最直观标志。然后试 PDFpretext build pdf如果成功output/pdf目录下会出现编译好的 PDF 文件。第一次跑 PDF 可能有点慢因为要启动 LaTeX 引擎还要跑一两遍交叉引用属于正常现象。3.3 publications.xml控制输出的总开关PreTeXt 里有一个叫publications的概念放在publications/publication.xml。它负责告诉引擎HTML 用什么方式渲染数学、PDF 用什么纸张和字体、输出目录结构怎么组织。默认生成的项目已经自带一份可用的publication.xml所以新手可以直接忽略它的存在。但如果你到了要定制样式那一步这个文件异常关键。比如 HTML 里公式渲染可以选择 MathJax 或 KaTeXKaTeX 通常更快PDF 里可以指定字体、字号、页面是否留出血线。我见过一些朋友在 project 里放着多个 publication 配置文件一份给线上预览一份给印刷厂这个用法很成熟。我的建议是一开始不要动publication.xml默认配置已经足够跑通全流程。等你对 PreTeXt 的输出体系有了整体认识再根据具体需求去改。4. 数学教材场景下最关键的能力Knowl 交互与习题体系如果你只写普通技术文档、个人博客PreTeXt 的学习曲线可能不太值得。但如果你写的是带大量公式、习题、答案、提示的数学或理工科教材它的优势会立刻显现出来。这一节我重点讲两个最打动我的能力Knowl 交互和习题体系。4.1 Knowl让内容折叠和推近而不是另开页面Knowl 是 PreTeXt 里一个很有代表性的交互概念。它允许作者在正文中插入一个可以点击展开的片段比如某句话的进一步解释、某个证明的详细过程、某个背景知识的补充。读者点击后内容就在当前位置展开不需要跳转到页面底部或另一个新页面。你可以把 Knowl 理解成 HTML 里details的高级版但它在整个系统里是一等公民可以出现在段落中间、习题旁边、表格注释里也能在 PDF 输出里自动转成可读的排版形式。我实际写讲义时特别喜欢把一些可给可不给的推导细节放进 Knowl这样正文的主线不会被冗长的证明打断感兴趣的同学又能自助展开看细节。教学场景里这种主线清晰 按需展开的节奏比传统的所有内容线性排列适合得多。传统 PDF 教材如果页面有限很多内容必须塞进正文或附录在网页版里Knowl 把主次关系和阅读节奏的选择权交还给了读者。4.2 习题、提示、答案、解答的自动组织教材写作中习题的处理最繁琐。同一个题目在教学周期里可能要经历先给学生看题目中途给一两个提示批改后给学生看答案最后课上讲评还要看完整解答。不同角色的读者应该看到不同的信息。传统做法是分别维护多份文档或者把答案统一放到书末。PreTeXt 的做法是把hint、answer、solution全部挂在同一个exercise下面让构建引擎根据输出格式决定怎么呈现。网页版里它们是可折叠的 KnowlPDF 里你可以通过配置让答案紧跟习题也可以统一集中到附录或者干脆在某一版里完全隐藏。我最后一次用 LaTeX 写教材时做学生版/教师版需要手动维护两个.tex文件后来用 PreTeXt 只需要在构建配置里改变一个选项。这一点在协作场景里更值钱。我见过一个团队十个人同时写讲义主文件全靠 Git 管理。如果每个人都去手工维护题号和答案位置冲突会让人崩溃PreTeXt 的自动编号机制让题目顺序任意调整编号和交叉引用都会自动更新极大减少了这类摩擦。4.3 xref 和自动编号终于不用手动维护第几章第几节长文档最痛苦的维护任务之一就是交叉引用。你辛辛苦苦写完详见第 4 章第 3 节结果在文章某处插入了一章所有数字全部失配还得逐个手动改。PreTeXt 用xref标签配合xml:id属性解决这个问题你引用的是一个节点的 ID构建时引擎自动生成对应的章节号和标题。比如在正文里写p完整证明见 xref refsec-hello/。/p无论章节编号怎么变生成的 HTML 和 PDF 里都会显示正确的编号和标题。这个功能对写论文、写教材这类动辄几百页、几十个引用的场景来说省下的时间非常可观。我现在已经习惯了把引用当作一种结构关系来维护而不是当作一个写死的文本片段。5. 我踩过的坑和绕开的弯路PreTeXt 整体设计思路很优雅但实际用下来也不是完全没有门槛。这里把我踩过的几个坑整理出来你提前看到可以少走冤枉路。5.1 XML 校验是第一个拦路虎既然源文件是 XML就要接受 XML 的严格语法。最常见的问题有三个标签忘记闭合、属性值忘加引号、在正文里直接用了符号。XML 里必须写成amp;必须写成lt;否则解析器直接报错。记得我最初写数学公式时习惯性地在文本里写类似Tom Jerry这样的表达结果构建失败报错信息指到了一个看起来完全没问题的段落。后来才反应过来是被当成实体开始符了。解决方式很简单正文里尽量用和或者以及如果必须写符号记得转义。另外一个实用建议是开发时始终保留一个终端窗口专门跑构建命令每次修改完源文件就构建一次。PreTeXt 的报错信息里会带文件路径和行号定位问题不算难。配合 VS Code 的 XML 插件做基础校验体验会好很多。5.2 PDF 中文/字体问题的处理如果你用 PreTeXt 写中文讲义HTML 输出一般没有大问题但 PDF 输出经常在字体这一关卡住。PreTeXt 的 PDF 后端走的是 XeLaTeX理论上可以直接调用系统字体但必须显式配置好中文字体。我最初跑 PDF 时遇到一堆 font 相关的报错一度以为是自己 TeX 发行版装坏了。后来总结出的经验是第一别用最小的 TeX Live 安装至少要把lang-chinese这类语言包补上第二先写一个只有标题和一行正文的小文件试编译把字体问题隔离出来再扩展到完整章节第三在publication.xml里明确指定字体不要依赖系统默认猜测。一旦把第一个中文 PDF 跑通后面的文档基本不会再踩同样的坑。5.3 表格、图片和自定义 LaTeX 宏包的边界PreTeXt 的表格用tabular标签它有一套自己的写法跟 LaTeX 的tabular环境很像但不是完全兼容。刚开始我直接把 LaTeX 表格源码贴进去构建报错后才发现要转换成tabular结构。图片则是用image标签里面可以指定source文件名、宽度还要写description描述文本这个描述不只是为了 SEO对无障碍阅读也是必须的。更重要的一点是PreTeXt 的 PDF 输出虽然后端是 LaTeX但它不会把任意 LaTeX 宏包能力都暴露给你。如果你在源文件里塞了一段自定义 LaTeX 命令HTML 输出往往无法对应渲染。所以写文档时应该首先寻找 PreTeXt 原生元素解决需求而不是习惯性回到 LaTeX 命令的舒适区。偶尔实在绕不开可以在 publication 配置里做局部 hack但要意识到这是有维护成本的。5.4 手动改输出不如改 source还有一个工作流上的坑一开始很容易犯。PreTeXt 每次构建都会重新生成output目录下的所有文件如果你手动去修改output/html里的某个 HTML 文件下次构建直接被覆盖。所以一切改动都要回到main.ptx和配置文件里做输出目录是产物不是源码。这个理念一开始会觉得不习惯毕竟 HTML 和 CSS 写了这么多年总想着直接改改前端。但换一个角度看它强迫你保持单一事实来源不会出现源代码是一回事线上环境是另一回事的分裂。对团队协作来说这反而是一种保护。6. 什么情况下我推荐你认真考虑 Pretext用了大概两个月之后我对 PreTeXt 的定位有了比较清楚的判断。它不是一个全场景的排版工具但在特定领域确实比 LaTeX 和 Markdown 顺手得多。6.1 最适合的人群和项目最匹配的场景是以教学为核心的长文档。比如大学数学、物理、计算机课程的讲义和教材开放教育资源OER项目需要同时提供网页版、打印版和电子版的出版物。这类内容的特点是公式密度高、习题体系复杂、需要大量交叉引用、并且常常有多人协作。如果你只是写个人博客或者简短的技术文章PreTeXt 的 XML 写法反而是负担Markdown 加 MathJax 就足够了。如果你需要高度定制化、版式极其花哨的书籍比如画册、杂志PreTeXt 也不是合适的工具直接上 InDesign 会更省事。PreTeXt 的甜区恰恰是内容结构复杂 输出形态多样 学术数学内容这三个条件交汇的地方。6.2 值得留意的成本PreTeXt 的学习曲线不能算低。XML 标签体系和 publication 配置初次接触需要花几天时间适应中文资料相对不多遇到问题大概率要查英文文档和示例仓库社区规模比 LaTeX 小很多提问得到响应的速度不如大社区。另一个隐性成本是生态锁定。PreTeXt 背后的工具链比较完整但如果你想在某个环节引入独特的 LaTeX 宏包可能需要花不少时间研究怎么把它封装进去。我在使用中尽量遵循它的原生语法而不是强行拼凑 LaTeX 代码这样才能把维护成本控制在可接受范围。6.3 我个人的使用建议如果你看完前面的介绍动心了我的建议是先只创建 HTML 构建别一上来就折腾 PDF。HTML 构建不依赖 LaTeX也不用面对中文字体问题能让你把注意力放在 PreTeXt 的语义化写作方式上。等你对标签体系熟悉了再逐步加 PDF 和 EPUB。第二个建议是先拿一本小册子做实验比如几十页的课程讲义而不是把几百页的旧文档一次性迁移过来。迁移过程会踩到各种边界情况小体积项目能帮你以最低成本摸清楚规则。我最初就是先用 PreTeXt 重写了一个三章的小讲义跑通全流程后才决定把它作为主力教材写作工具。第三个建议多去翻官方文档和示例仓库。PreTeXt 的文档工程做得不错几乎每个标签都有配套的示例直接改造示例比自己从零摸索快得多。真实项目里也会藏很多非常规的用法比如怎么处理多选题、怎么把外部 WebWork 习题嵌进来这些在官方示例里都能找到参考。我自己实践下来最大的感受是PreTeXt 把排版这个原本让人觉得必须靠技术功底解决的问题重新还原成了内容结构问题。一旦结构清楚输出自然水到渠成。如果你恰好也在为一个公式密集、习题众多、还想同时照顾网页和纸质读者的项目发愁不妨花一个周末从最小示例跑起来它会让你对文本排版引擎产生一些新的想法。