这半年我一直在维护一份面向数学专业学生的开源讲义从 Word 到 Markdown 再到 LaTeX 都折腾过一轮最后卡在一个非常现实的问题上同一套内容既要有适合在线阅读的网页版又要能生成发给印刷厂的 PDF偶尔还要导出 EPUB 给平板阅读。用 LaTeX 写内容没问题但同一份 LaTeX 想再生成网页基本等于重写一遍。后来在一个数学教学社区里看到别人推荐Pretext官方拼写 PreTeXt中文社区一般叫 Pretext这个文本排版引擎抱着试试看的心态用了一个月我发现这可能是目前把“单一内容来源”和“多格式输出”结合得最舒服的解决方案之一。这不是一个商业软件也不是某个大厂的产品而是由美国数学研究所AIM推动、数学教材社区维护的开源项目。它的最大特点是把写作拆成“内容结构”和“视觉呈现”两层你只负责用 XML 标签描述文档的语义结构——这是章节、这是定理、这是公式、这是习题——至于网页端的折叠交互、PDF 里的排版样式、EPUB 里的章节切分全部由 Pretext 自己处理。听起来有点像 Markdown 的思路但它的结构化能力比 Markdown 强得多尤其是对数学公式、定理环境、交叉引用这些学术写作刚需的支持是 Markdown 完全做不到的。如果你是数学、物理、计算机等理工科方向的写作者需要长期维护讲义、教材或技术文档并且希望同一份内容在不同平台都能获得体面的呈现那 Pretext 非常值得花一个下午认真试一下。这篇博文我会从设计原理、上手流程、实战对比、踩坑经验几个角度完整拆一遍结尾再聊聊它适合谁、不适合谁。1. Pretext 到底是什么一个以内容为中心的排版方案1.1 一句话概括与定位Pretext 是一个基于 XML 的语义化文本排版引擎。它不像 Word 那样“所见即所得”也不像 LaTeX 那样让你通过底层命令直接控制排版细节。它的核心哲学是作者只负责标记一段文本的意义而不是样子。举一个最简单的例子。在 LaTeX 里你写\begin{theorem} 如果 $a^2b^2c^2$那么这是一个直角三角形。 \end{theorem}在 Pretext 里你写theorem statement p如果 ma^2 b^2 c^2/m那么这是一个直角三角形。/p /statement /theorem表面上看差别不大但 LaTeX 的theorem环境最终只会生成一个带编号的定理块而 Pretext 的theorem标签保留了“这是一个定理”的语义。同样一段 XML生成 HTML 网页时会自动带上编号和样式生成 PDF 时会按印刷排版规则处理生成 EPUB 时会变成一个独立的内容块。更重要的是任何地方通过xref引用这个定理时系统会自动算出正确的编号和链接你永远不需要手动维护“定理 3.2”这种编号。1.2 和其他排版工具的本质差异可以把常用排版工具放在一条光谱上看Word / WPS典型“所见即所得”上手最快但大型文档的样式一致性、交叉引用、自动编号是灾难源。改一个标题的格式可能导致二十个地方不一致。Markdown轻量级结构化写博客、README 很舒服但遇到公式、定理、复杂交叉引用就力不从心。虽然能通过扩展语法支持公式但整体的语义化程度有限。LaTeX排版质量天花板控制力极强但作者把大量精力花在“控制排版”上而且要写双份代码才能出网页版。Pretext站在作者与最终呈现之间作者写结构引擎管呈现。它的输入是 XML因此可以承载远比 Markdown 复杂的语义信息输出质量虽然不一定能达到 LaTeX 的极致但对绝大多数教材、讲义、技术文档来说已经是“很体面”的水平。我个人的体会是工具选型的核心不是“哪个更强大”而是“哪个更适合长期维护”。LaTeX 适合论文投稿这类“一次成型、格式固定”的场景而如果你要维护一套几年持续迭代的教材Pretext 的单源多输出优势会随着时间越放越大。1.3 它适合谁用不适合谁用从实际使用场景来说Pretext 最适合三类人高校教师或培训机构讲师需要长期维护讲义、课件、习题集希望学生既能在线看、也能下载 PDF 打印。开源技术文档维护者项目文档包含大量公式、算法、代码示例且需要在 Web 端保持良好阅读体验。中小型出版机构的技术编辑需要从统一的内容源生成不同版式的电子版和印刷版。反过来如果你只是想快速写一篇几页纸的短文、做一份简单的简历那 Pretext 属于杀鸡用牛刀Markdown 甚至纯文本就够了。此外Pretext 对数学公式支持极好但如果你写的是纯代码文档或纯文科内容它的优势就体现不出来了。2. 核心设计拆解语义化标记如何改变写作流程2.1 同一个源文件多渠道输出Pretext 最核心的设计目标是“单源多输出”single sourcemulti output。你只有一个.ptx的 XML 源文件但可以通过不同的构建命令生成HTML 网页适合在线阅读自动生成目录、侧边栏、搜索框、折叠的解决方案Pretext 称之为 Knowl。PDF通过 LaTeX 引擎排版输出适合打印或印刷的版本。EPUB适合平板、电子书阅读器。纯文本 / Jupyter Book 等插件输出社区还在不断扩展。这个设计带来的实际好处是你永远只需要维护一份内容。以前我用 LaTeX 写讲义每逢学期初改版要把 PDF 里发现的修改同步回源文件后来尝试过用 Markdown 写再通过 Pandoc 转 PDF但公式和定理编号始终差强人意。现在用 Pretext我只需要在 XML 里改内容网页版和 PDF 版同时更新再也不会有“两个版本不一致”的问题。2.2 数学公式、定理与交叉引用这是 Pretext 相比 Markdown 最碾压的地方。数学公式使用m表示行内公式、md表示展示公式display math在 HTML 输出时通过 MathJax 渲染在 PDF 输出时由 LaTeX 处理。你不需要关心网页端公式是怎么加载、PDF 端公式是用什么宏包——引擎全部接管了。定理环境更是学术写作的刚需。Pretext 内置了theorem、definition、example、algorithm、remark、exercise等丰富的语义标签。它们会自动进入统一的编号体系而且可以跨章节精确引用。比如你在第 2 章定义了一个引理lemma xml:idlem-key-inequality statement p对于任意非负实数 mx, y/m满足 mx y \geq 2\sqrt{xy}/m。/p /statement /lemma然后在第 5 章引用它p根据 xref reflem-key-inequality /我们可以直接得出结论。/p无论你怎么调整章节顺序、增删定理PDF 和网页里的编号都会自动更新。这在长文档写作中省下的心力是巨大的。2.3 可访问性与交互性Pretext 对可访问性accessibility的重视是它和 LaTeX 最明显的精神差异。HTML 输出中的数学公式使用 MathML 或配合 MathJax 的辅助模式对屏幕阅读器友好结构化的标题、列表、表格天然携带语义标记方便读屏软件导航。这一点在 LaTeX 生成的 PDF 里很难做到。同时Pretext 原生支持一系列“参与式组件”interactive elements比如网页端的可折叠内容、可以让读者点击展开的“Knovel”提示框、通过滑块调整参数并实时看到变化的动态图表组件如slider、ramp、kbtn。这些组件在教学场景下非常好用——学生可以直接在网页上拖动参数看函数图像的变化而教师只需要在源文件里写一段 XML不需要写任何 JavaScript。2.4 严格 XML好处的另一面是学习曲线Pretext 采用 XML Schema 做严格校验。这意味着你的源文件必须结构精确闭合标签用错就会构建失败。一开始你可能觉得繁琐但长远看这是保护它保证了你几十章文档的格式一致性不会出现“第 20 章少个闭合标签导致整本书排版错乱”这种在 LaTeX 里常遇到的事故。不过也因此Pretext 的上手门槛比 Markdown 高不少需要花几个小时熟悉标签体系和 XML 的语法规则。好在官方文档非常详细而且社区提供了大量开源教材的.ptx源码直接拿一本模仿著写是最快的入门方式。3. 从零上手环境准备与第一篇文档3.1 安装与项目初始化这里我以 macOS / Linux 环境为例说明Windows 上逻辑相同但部分命令可能有细微差别。首先确认本机已安装 Python 3.8 以上版本然后执行pip install pretext这会安装 Pretext 的命令行工具。接着初始化一个新项目pretext new demo-book cd demo-book命令执行后会自动生成一个标准目录结构demo-book/ ├── source/ │ ├── main.ptx │ ├── image/ │ └── ... ├── build/ ├── project.ptx └── README.md关键在于source/main.ptx这是你的内容源文件project.ptx是项目配置文件定义书名、作者、语言、输出选项等。第一次构建 PDF 之前需要确保本机装有完整的 LaTeX 发行版TeX Live 或 MacTeX。如果你不打算出 PDF只出网页版可以跳过这一步。但通常还是建议装上因为有些 HTML 特性比如数学公式的某些导出也会依赖 LaTeX 工具链。提示如果你不想在本机安装庞大的 TeX Live也可以用官方提供的 Docker 镜像pretextbook/pretext全部工具链都封装在里面一条命令即可完成构建。3.2 编写第一个 ptx 文件打开source/main.ptx简单改成这样?xml version1.0 encodingUTF-8? pretext docinfo author personname你的名字/personname /author title我的第一本 Pretext 测试书/title /docinfo book chapter title快速上手/title section title第一个段落/title p 你好这是 ma^2 b^2 c^2/m 公式示例。 /p p 这是一个定理 theorem xml:idthm-pythagoras statement p直角三角形的两直角边平方和等于斜边平方。/p /statement /theorem /p p 引用定理xref refthm-pythagoras / /p /section /chapter /book /pretext注意两点。第一pretext是根元素所有内容都必须在它内部。第二xml:id是交叉引用的锚点建议从第一天就用有意义的英文命名比如thm-pythagoras、sec-introduction不要用sec1、def2这种将来你自己都懒得查的名字。3.3 生成 HTML 和 PDF构建网页版只需要一条命令pretext build html构建完成后在项目根目录下会生成build文件夹里面按输出类型分子目录存放生成结果。用浏览器打开对应的index.html就能预览。你会在网页里看到一个带侧边栏目录、顶部搜索框、公式可以鼠标悬停放大的现代风格文档完全不像传统 XML 工具链产出的那种“工程样”页面。构建 PDFpretext build pdf第一次执行会调用 LaTeX 引擎编译耗时可能长一些之后增量编译会快很多。成功后在build目录下找到生成的 PDF 文件打开看看封面、目录、定理编号、交叉引用、数学公式全部自动排好了。这里要特别提醒即使你最终只打算发布 PDF我也建议先执行一次pretext build html看看网页版效果。Pretext 在网页端的排版质量非常出众很多时候我的编辑反馈提出的修改意见反而是先在网页版上发现的——因为网页上更容易比较不同章节的结构一致性。3.4 常用命令速查表命令作用备注pretext new name初始化新项目生成标准目录结构pretext build html构建网页版输出到build目录pretext build pdf构建 PDF需要本机 LaTeXpretext build epub构建电子书EPUB 格式pretext build format --watch监听文件变化并自动重新构建适合写作时实时预览pretext build clean清空构建缓存有时“奇怪问题”靠这招解决4. 实战对比LaTeX、Markdown 和 Pretext 怎么选4.1 LaTeX排版之王与它的痛点我用了六七年 LaTeX至今认为它的排版质量是所有工具里最顶级的。但它的痛点同样明显重排版、轻内容。写作过程中你脑子里同时要装两件事——内容逻辑和排版控制。\begin{...}、\label{...}、\vspace{...}这些控制序列穿插在内容里阅读源码时很难快速看出文章结构。另一个更现实的问题是LaTeX 的世界天生是“PDF 中心主义”的。HHTP 输出要么靠 Pandoc 转的网页要么靠 LaTeX 的 hyperref 生成的简单 HTML交互性基本为零。这就导致如果你需要在线教学环境LaTeX 的工作流必须额外接入一套完全不同的 Web 系统维护成本成倍增加。4.2 Markdown轻量但难以上升到专著Markdown 在简短文档中是效率之王这个没有争议。但对于一本 300 页以上的教材Markdown 的结构能力明显力不从心。你确实可以用#/##表示章节但“定理”“定义”“示例”这类语义单元没有原生支持往往只能用**定理 3.2.**这种手写方式编号一旦错乱就全完。虽然可以结合 Pandoc 扩展语法和模板做一定程度的自动化但每当你需要修改一个模板细节就要钻进 Pandoc 的 Lua 过滤器里调整——这个复杂度已经逼近甚至超过直接学 Pretext 的 XML 了。4.3 选型建议按场景决策做个直观的对比维度LaTeXMarkdownPretext学习曲线陡峭平缓中等数学公式支持极好一般需扩展极好定理/交叉引用好但需手动维护弱原生支持多格式输出PDF 为主其他较弱通过 Pandoc 中转HTML/PDF/EPUB 一等公民可交互性弱弱原生组件可访问性一般一般优秀适合文档规模论文、小书博客、短文教材、讲义、技术书我的选型经验是5 页以内用 Markdown50 页论文用 LaTeX500 页教材且需要网页版本用 Pretext。如果你的项目正好卡在中间地带我建议可以先用 Markdown 写初稿等结构稳定后迁移到 Pretext——虽然迁移过程需要手动补 XML 标签但总比写到一半发现工具天花板再来转轻松得多。5. 实操中的常见问题与避坑5.1 中文支持配置这是中文用户最关心的问题。Pretext 对中文的支持不是开箱即用的需要额外配置。我自己踩过的坑主要有两个第一在project.ptx中设置文档语言为中文docinfo language xml:langzh-CN / /docinfo这会影响生成的 HTML 页面html langzh-CN属性和 PDF 中的语言选项。第二PDF 输出需要保证 LaTeX 引擎使用 XeLaTeX 或 LuaLaTeXPretext 默认的 PDF 构建基于 LaTeX但可以通过配置切换这样才能正确处理中文字符。我在第一次构建 PDF 时中文全部变成乱码排查后发现是默认编译器没有启用中文支持。解决方案是在项目配置中指定使用xelatex同时安装必要的 CJK 字体和中文字体宏包。提示中文字体的配置最好在项目一开始就验证好而不是等写了十几章才临时处理。否则到时候几百个中文字符在 PDF 里乱码排查起来非常痛苦。5.2 数学公式在网页端不显示如果你生成的 HTML 中公式是一片空白或原始 LaTeX 源码最常见的原因是浏览器没有加载 MathJax。Pretext 默认生成的 HTML 需要联网引用 MathJax 资源如果你在内网环境或者浏览器网络受限公式就会失效。解决办法是在project.ptx中配置本地 MathJax 资源路径或者下载 MathJax 到服务器上离线引用。我个人的建议是直接改成离线引用——反正教材资源一般会长期挂在服务器上避免日后读者网络问题导致公式无法加载的尴尬。5.3 交叉引用的标签检查Pretext 的交叉引用很强大但前提是xml:id必须全局唯一。我在一次大规模重构时把一个章节整体复制到另一个章节结果忘了修改内部的xml:id导致构建时报“duplicate id”错误浏览器上点击引用链接也跳转错误的位置。这个问题的排查方法是构建时查看报错信息中的具体行号和标签名全局搜索定位。为了避免再犯我现在规定项目内所有xml:id必须带前缀章节用sec-定理用thm-定义用def-习题用exe-一眼就能知道引用目标是什么类型也能避免重名。5.4 PDF 字体与宏包问题Pretext 的 PDF 构建本质上还是依赖 LaTeX 工具链所以你可能会遇到 LaTeX 时代的经典问题缺少宏包、字体文件不对、编译报错。最常见的场景是在使用特殊数学符号时默认的 LaTeX 宏包集合不够用。我的处理思路是直接用 TeX Live 全量安装不要为了省磁盘空间而选择 minimal 版否则后续各种宏包缺失会无穷无尽地折磨你。另外在 Pretext 中加入自定义 LaTeX 宏包需要在project.ptx的latex-preamble中声明不像 LaTeX 里直接\usepackage那样随手。5.5 自定义样式与品牌化Pretext 默认的网页主题非常整洁但如果你要嵌入到学校或公司的品牌体系中默认样式可能不够。网页端可以通过自定义 CSS 文件调整整体视觉风格PDF 端则通过修改 LaTeX 模板配置。这部分官方文档有一章专门介绍“Customization”但我的建议是等到内容稳定后再去动样式。因为 Pretext 的主题已经足够耐看过早定制样式会导致后续版本升级时需要同步维护工作量不小。6. 进阶玩法构建交互式教学文档6.1 参与式演示组件Pretext 最有意思的进阶功能是“参与式组件”。比如你想让学生直观理解二次函数参数变化对图像的影响传统做法是插入一张静态图或者放一个外部 JavaScript 应用。而在 Pretext 里你可以用内置组件实现一个可拖拽参数的交互图figure title调整参数观察抛物线变化/title interactive slider namea labela min-3 max3 initial1 / slider nameb labelb min-3 max3 initial0 / slider namec labelc min-3 max3 initial0 / kplot functiona*x^2 b*x c/function /kplot /interactive /figure这段 XML 在生成的网页中会变成一个带有三个滑块的交互图表学生拖拽滑块时函数图像实时变化。教师不需要学 JavaScript不需要自己写可视化库一切都由 Pretext 包装好的组件自动完成。这是我目前认为 Pretext 相比 LaTeX 最具备“降维打击”能力的地方。6.2 集成在线作业系统如果你是数学老师可能听说过 WeBWorK一个开源的在线作业系统。Pretext 和 WeBWorK 有官方集成。在 XML 中写exercise标签并关联到 WeBWorK 题库学生提交的答案会自动送进 WeBWorK 评分系统成绩自动登记。这意味着什么你可以用 Pretext 写一份完整的电子教材每一节后面的练习题直接对接能自动评分、即时反馈的系统。学生从阅读到练习再到得到反馈整个流程都在同一个学习环境中完成。这在传统课程建设中是相当难实现的一体化体验。6.3 维护大型教材项目的经验最后聊一点项目工程化的经验。用 Pretext 维护大型教材时我有一个非常推荐的习惯一个章节至少拆成独立文件用xi:include包含到主文件中。比如main.ptx中book xi:include hrefchapters/chapter1.ptx / xi:include hrefchapters/chapter2.ptx / xi:include hrefchapters/chapter3.ptx / /book这样每个章节是独立文件多人协作时冲突更少单文件的行数也不会膨胀到编辑器都卡顿的地步。配合 Git 做版本管理每次修改的 diff 也清晰得多。我在最初维护时把所有内容写在一个main.ptx里到第 10 章后每次用编辑器打开都要等几秒钟后来拆分成章节文件体验立刻好多了。6.4 社区与生态Pretext 的社区规模不大但非常活跃。Github 上有PreTeXtBook的组织官方文档站pretextbook.org有从入门到高级的完整教程。社区维护了一批高质量的开源教材其中不少是美国大学的数学课程指定教材。直接下载这些教材的源码查看别人是怎么组织章节、怎么处理练习题、怎么设计交互式组件是我认为最高效的学习方式。最后说点实在的用 Pretext 这段时间我对“排版工具”这件事的认知有一些变化。以前我总觉得工具越强越好、控制力越精细越好现在则认为真正顺手的工具是让内容自己浮现出来、让形式自动退到后台的工具。Pretext 并不是没有缺点XML 标签冗长手写时容易被结构细节干扰自定义样式的自由度远不如直接写 LaTeX学习曲线相比 Markdown 陡了很多。但它解决的问题——一份内容多端分发长期维护可访问性——正是当前教育数字化环境下越来越多人会面对的痛点。如果这恰好也是你的痛点我建议你留出一个下午按这篇文章的步骤跑通第一个小项目然后再决定要不要把长期写作迁移过来。至少我自己的教材项目目前已经彻底从 LaTeX 切换到了 Pretext并且没有回退的打算。 Pretext：语义化排版引擎，让教材写作一次编写多端发布
这半年我一直在维护一份面向数学专业学生的开源讲义从 Word 到 Markdown 再到 LaTeX 都折腾过一轮最后卡在一个非常现实的问题上同一套内容既要有适合在线阅读的网页版又要能生成发给印刷厂的 PDF偶尔还要导出 EPUB 给平板阅读。用 LaTeX 写内容没问题但同一份 LaTeX 想再生成网页基本等于重写一遍。后来在一个数学教学社区里看到别人推荐Pretext官方拼写 PreTeXt中文社区一般叫 Pretext这个文本排版引擎抱着试试看的心态用了一个月我发现这可能是目前把“单一内容来源”和“多格式输出”结合得最舒服的解决方案之一。这不是一个商业软件也不是某个大厂的产品而是由美国数学研究所AIM推动、数学教材社区维护的开源项目。它的最大特点是把写作拆成“内容结构”和“视觉呈现”两层你只负责用 XML 标签描述文档的语义结构——这是章节、这是定理、这是公式、这是习题——至于网页端的折叠交互、PDF 里的排版样式、EPUB 里的章节切分全部由 Pretext 自己处理。听起来有点像 Markdown 的思路但它的结构化能力比 Markdown 强得多尤其是对数学公式、定理环境、交叉引用这些学术写作刚需的支持是 Markdown 完全做不到的。如果你是数学、物理、计算机等理工科方向的写作者需要长期维护讲义、教材或技术文档并且希望同一份内容在不同平台都能获得体面的呈现那 Pretext 非常值得花一个下午认真试一下。这篇博文我会从设计原理、上手流程、实战对比、踩坑经验几个角度完整拆一遍结尾再聊聊它适合谁、不适合谁。1. Pretext 到底是什么一个以内容为中心的排版方案1.1 一句话概括与定位Pretext 是一个基于 XML 的语义化文本排版引擎。它不像 Word 那样“所见即所得”也不像 LaTeX 那样让你通过底层命令直接控制排版细节。它的核心哲学是作者只负责标记一段文本的意义而不是样子。举一个最简单的例子。在 LaTeX 里你写\begin{theorem} 如果 $a^2b^2c^2$那么这是一个直角三角形。 \end{theorem}在 Pretext 里你写theorem statement p如果 ma^2 b^2 c^2/m那么这是一个直角三角形。/p /statement /theorem表面上看差别不大但 LaTeX 的theorem环境最终只会生成一个带编号的定理块而 Pretext 的theorem标签保留了“这是一个定理”的语义。同样一段 XML生成 HTML 网页时会自动带上编号和样式生成 PDF 时会按印刷排版规则处理生成 EPUB 时会变成一个独立的内容块。更重要的是任何地方通过xref引用这个定理时系统会自动算出正确的编号和链接你永远不需要手动维护“定理 3.2”这种编号。1.2 和其他排版工具的本质差异可以把常用排版工具放在一条光谱上看Word / WPS典型“所见即所得”上手最快但大型文档的样式一致性、交叉引用、自动编号是灾难源。改一个标题的格式可能导致二十个地方不一致。Markdown轻量级结构化写博客、README 很舒服但遇到公式、定理、复杂交叉引用就力不从心。虽然能通过扩展语法支持公式但整体的语义化程度有限。LaTeX排版质量天花板控制力极强但作者把大量精力花在“控制排版”上而且要写双份代码才能出网页版。Pretext站在作者与最终呈现之间作者写结构引擎管呈现。它的输入是 XML因此可以承载远比 Markdown 复杂的语义信息输出质量虽然不一定能达到 LaTeX 的极致但对绝大多数教材、讲义、技术文档来说已经是“很体面”的水平。我个人的体会是工具选型的核心不是“哪个更强大”而是“哪个更适合长期维护”。LaTeX 适合论文投稿这类“一次成型、格式固定”的场景而如果你要维护一套几年持续迭代的教材Pretext 的单源多输出优势会随着时间越放越大。1.3 它适合谁用不适合谁用从实际使用场景来说Pretext 最适合三类人高校教师或培训机构讲师需要长期维护讲义、课件、习题集希望学生既能在线看、也能下载 PDF 打印。开源技术文档维护者项目文档包含大量公式、算法、代码示例且需要在 Web 端保持良好阅读体验。中小型出版机构的技术编辑需要从统一的内容源生成不同版式的电子版和印刷版。反过来如果你只是想快速写一篇几页纸的短文、做一份简单的简历那 Pretext 属于杀鸡用牛刀Markdown 甚至纯文本就够了。此外Pretext 对数学公式支持极好但如果你写的是纯代码文档或纯文科内容它的优势就体现不出来了。2. 核心设计拆解语义化标记如何改变写作流程2.1 同一个源文件多渠道输出Pretext 最核心的设计目标是“单源多输出”single sourcemulti output。你只有一个.ptx的 XML 源文件但可以通过不同的构建命令生成HTML 网页适合在线阅读自动生成目录、侧边栏、搜索框、折叠的解决方案Pretext 称之为 Knowl。PDF通过 LaTeX 引擎排版输出适合打印或印刷的版本。EPUB适合平板、电子书阅读器。纯文本 / Jupyter Book 等插件输出社区还在不断扩展。这个设计带来的实际好处是你永远只需要维护一份内容。以前我用 LaTeX 写讲义每逢学期初改版要把 PDF 里发现的修改同步回源文件后来尝试过用 Markdown 写再通过 Pandoc 转 PDF但公式和定理编号始终差强人意。现在用 Pretext我只需要在 XML 里改内容网页版和 PDF 版同时更新再也不会有“两个版本不一致”的问题。2.2 数学公式、定理与交叉引用这是 Pretext 相比 Markdown 最碾压的地方。数学公式使用m表示行内公式、md表示展示公式display math在 HTML 输出时通过 MathJax 渲染在 PDF 输出时由 LaTeX 处理。你不需要关心网页端公式是怎么加载、PDF 端公式是用什么宏包——引擎全部接管了。定理环境更是学术写作的刚需。Pretext 内置了theorem、definition、example、algorithm、remark、exercise等丰富的语义标签。它们会自动进入统一的编号体系而且可以跨章节精确引用。比如你在第 2 章定义了一个引理lemma xml:idlem-key-inequality statement p对于任意非负实数 mx, y/m满足 mx y \geq 2\sqrt{xy}/m。/p /statement /lemma然后在第 5 章引用它p根据 xref reflem-key-inequality /我们可以直接得出结论。/p无论你怎么调整章节顺序、增删定理PDF 和网页里的编号都会自动更新。这在长文档写作中省下的心力是巨大的。2.3 可访问性与交互性Pretext 对可访问性accessibility的重视是它和 LaTeX 最明显的精神差异。HTML 输出中的数学公式使用 MathML 或配合 MathJax 的辅助模式对屏幕阅读器友好结构化的标题、列表、表格天然携带语义标记方便读屏软件导航。这一点在 LaTeX 生成的 PDF 里很难做到。同时Pretext 原生支持一系列“参与式组件”interactive elements比如网页端的可折叠内容、可以让读者点击展开的“Knovel”提示框、通过滑块调整参数并实时看到变化的动态图表组件如slider、ramp、kbtn。这些组件在教学场景下非常好用——学生可以直接在网页上拖动参数看函数图像的变化而教师只需要在源文件里写一段 XML不需要写任何 JavaScript。2.4 严格 XML好处的另一面是学习曲线Pretext 采用 XML Schema 做严格校验。这意味着你的源文件必须结构精确闭合标签用错就会构建失败。一开始你可能觉得繁琐但长远看这是保护它保证了你几十章文档的格式一致性不会出现“第 20 章少个闭合标签导致整本书排版错乱”这种在 LaTeX 里常遇到的事故。不过也因此Pretext 的上手门槛比 Markdown 高不少需要花几个小时熟悉标签体系和 XML 的语法规则。好在官方文档非常详细而且社区提供了大量开源教材的.ptx源码直接拿一本模仿著写是最快的入门方式。3. 从零上手环境准备与第一篇文档3.1 安装与项目初始化这里我以 macOS / Linux 环境为例说明Windows 上逻辑相同但部分命令可能有细微差别。首先确认本机已安装 Python 3.8 以上版本然后执行pip install pretext这会安装 Pretext 的命令行工具。接着初始化一个新项目pretext new demo-book cd demo-book命令执行后会自动生成一个标准目录结构demo-book/ ├── source/ │ ├── main.ptx │ ├── image/ │ └── ... ├── build/ ├── project.ptx └── README.md关键在于source/main.ptx这是你的内容源文件project.ptx是项目配置文件定义书名、作者、语言、输出选项等。第一次构建 PDF 之前需要确保本机装有完整的 LaTeX 发行版TeX Live 或 MacTeX。如果你不打算出 PDF只出网页版可以跳过这一步。但通常还是建议装上因为有些 HTML 特性比如数学公式的某些导出也会依赖 LaTeX 工具链。提示如果你不想在本机安装庞大的 TeX Live也可以用官方提供的 Docker 镜像pretextbook/pretext全部工具链都封装在里面一条命令即可完成构建。3.2 编写第一个 ptx 文件打开source/main.ptx简单改成这样?xml version1.0 encodingUTF-8? pretext docinfo author personname你的名字/personname /author title我的第一本 Pretext 测试书/title /docinfo book chapter title快速上手/title section title第一个段落/title p 你好这是 ma^2 b^2 c^2/m 公式示例。 /p p 这是一个定理 theorem xml:idthm-pythagoras statement p直角三角形的两直角边平方和等于斜边平方。/p /statement /theorem /p p 引用定理xref refthm-pythagoras / /p /section /chapter /book /pretext注意两点。第一pretext是根元素所有内容都必须在它内部。第二xml:id是交叉引用的锚点建议从第一天就用有意义的英文命名比如thm-pythagoras、sec-introduction不要用sec1、def2这种将来你自己都懒得查的名字。3.3 生成 HTML 和 PDF构建网页版只需要一条命令pretext build html构建完成后在项目根目录下会生成build文件夹里面按输出类型分子目录存放生成结果。用浏览器打开对应的index.html就能预览。你会在网页里看到一个带侧边栏目录、顶部搜索框、公式可以鼠标悬停放大的现代风格文档完全不像传统 XML 工具链产出的那种“工程样”页面。构建 PDFpretext build pdf第一次执行会调用 LaTeX 引擎编译耗时可能长一些之后增量编译会快很多。成功后在build目录下找到生成的 PDF 文件打开看看封面、目录、定理编号、交叉引用、数学公式全部自动排好了。这里要特别提醒即使你最终只打算发布 PDF我也建议先执行一次pretext build html看看网页版效果。Pretext 在网页端的排版质量非常出众很多时候我的编辑反馈提出的修改意见反而是先在网页版上发现的——因为网页上更容易比较不同章节的结构一致性。3.4 常用命令速查表命令作用备注pretext new name初始化新项目生成标准目录结构pretext build html构建网页版输出到build目录pretext build pdf构建 PDF需要本机 LaTeXpretext build epub构建电子书EPUB 格式pretext build format --watch监听文件变化并自动重新构建适合写作时实时预览pretext build clean清空构建缓存有时“奇怪问题”靠这招解决4. 实战对比LaTeX、Markdown 和 Pretext 怎么选4.1 LaTeX排版之王与它的痛点我用了六七年 LaTeX至今认为它的排版质量是所有工具里最顶级的。但它的痛点同样明显重排版、轻内容。写作过程中你脑子里同时要装两件事——内容逻辑和排版控制。\begin{...}、\label{...}、\vspace{...}这些控制序列穿插在内容里阅读源码时很难快速看出文章结构。另一个更现实的问题是LaTeX 的世界天生是“PDF 中心主义”的。HHTP 输出要么靠 Pandoc 转的网页要么靠 LaTeX 的 hyperref 生成的简单 HTML交互性基本为零。这就导致如果你需要在线教学环境LaTeX 的工作流必须额外接入一套完全不同的 Web 系统维护成本成倍增加。4.2 Markdown轻量但难以上升到专著Markdown 在简短文档中是效率之王这个没有争议。但对于一本 300 页以上的教材Markdown 的结构能力明显力不从心。你确实可以用#/##表示章节但“定理”“定义”“示例”这类语义单元没有原生支持往往只能用**定理 3.2.**这种手写方式编号一旦错乱就全完。虽然可以结合 Pandoc 扩展语法和模板做一定程度的自动化但每当你需要修改一个模板细节就要钻进 Pandoc 的 Lua 过滤器里调整——这个复杂度已经逼近甚至超过直接学 Pretext 的 XML 了。4.3 选型建议按场景决策做个直观的对比维度LaTeXMarkdownPretext学习曲线陡峭平缓中等数学公式支持极好一般需扩展极好定理/交叉引用好但需手动维护弱原生支持多格式输出PDF 为主其他较弱通过 Pandoc 中转HTML/PDF/EPUB 一等公民可交互性弱弱原生组件可访问性一般一般优秀适合文档规模论文、小书博客、短文教材、讲义、技术书我的选型经验是5 页以内用 Markdown50 页论文用 LaTeX500 页教材且需要网页版本用 Pretext。如果你的项目正好卡在中间地带我建议可以先用 Markdown 写初稿等结构稳定后迁移到 Pretext——虽然迁移过程需要手动补 XML 标签但总比写到一半发现工具天花板再来转轻松得多。5. 实操中的常见问题与避坑5.1 中文支持配置这是中文用户最关心的问题。Pretext 对中文的支持不是开箱即用的需要额外配置。我自己踩过的坑主要有两个第一在project.ptx中设置文档语言为中文docinfo language xml:langzh-CN / /docinfo这会影响生成的 HTML 页面html langzh-CN属性和 PDF 中的语言选项。第二PDF 输出需要保证 LaTeX 引擎使用 XeLaTeX 或 LuaLaTeXPretext 默认的 PDF 构建基于 LaTeX但可以通过配置切换这样才能正确处理中文字符。我在第一次构建 PDF 时中文全部变成乱码排查后发现是默认编译器没有启用中文支持。解决方案是在项目配置中指定使用xelatex同时安装必要的 CJK 字体和中文字体宏包。提示中文字体的配置最好在项目一开始就验证好而不是等写了十几章才临时处理。否则到时候几百个中文字符在 PDF 里乱码排查起来非常痛苦。5.2 数学公式在网页端不显示如果你生成的 HTML 中公式是一片空白或原始 LaTeX 源码最常见的原因是浏览器没有加载 MathJax。Pretext 默认生成的 HTML 需要联网引用 MathJax 资源如果你在内网环境或者浏览器网络受限公式就会失效。解决办法是在project.ptx中配置本地 MathJax 资源路径或者下载 MathJax 到服务器上离线引用。我个人的建议是直接改成离线引用——反正教材资源一般会长期挂在服务器上避免日后读者网络问题导致公式无法加载的尴尬。5.3 交叉引用的标签检查Pretext 的交叉引用很强大但前提是xml:id必须全局唯一。我在一次大规模重构时把一个章节整体复制到另一个章节结果忘了修改内部的xml:id导致构建时报“duplicate id”错误浏览器上点击引用链接也跳转错误的位置。这个问题的排查方法是构建时查看报错信息中的具体行号和标签名全局搜索定位。为了避免再犯我现在规定项目内所有xml:id必须带前缀章节用sec-定理用thm-定义用def-习题用exe-一眼就能知道引用目标是什么类型也能避免重名。5.4 PDF 字体与宏包问题Pretext 的 PDF 构建本质上还是依赖 LaTeX 工具链所以你可能会遇到 LaTeX 时代的经典问题缺少宏包、字体文件不对、编译报错。最常见的场景是在使用特殊数学符号时默认的 LaTeX 宏包集合不够用。我的处理思路是直接用 TeX Live 全量安装不要为了省磁盘空间而选择 minimal 版否则后续各种宏包缺失会无穷无尽地折磨你。另外在 Pretext 中加入自定义 LaTeX 宏包需要在project.ptx的latex-preamble中声明不像 LaTeX 里直接\usepackage那样随手。5.5 自定义样式与品牌化Pretext 默认的网页主题非常整洁但如果你要嵌入到学校或公司的品牌体系中默认样式可能不够。网页端可以通过自定义 CSS 文件调整整体视觉风格PDF 端则通过修改 LaTeX 模板配置。这部分官方文档有一章专门介绍“Customization”但我的建议是等到内容稳定后再去动样式。因为 Pretext 的主题已经足够耐看过早定制样式会导致后续版本升级时需要同步维护工作量不小。6. 进阶玩法构建交互式教学文档6.1 参与式演示组件Pretext 最有意思的进阶功能是“参与式组件”。比如你想让学生直观理解二次函数参数变化对图像的影响传统做法是插入一张静态图或者放一个外部 JavaScript 应用。而在 Pretext 里你可以用内置组件实现一个可拖拽参数的交互图figure title调整参数观察抛物线变化/title interactive slider namea labela min-3 max3 initial1 / slider nameb labelb min-3 max3 initial0 / slider namec labelc min-3 max3 initial0 / kplot functiona*x^2 b*x c/function /kplot /interactive /figure这段 XML 在生成的网页中会变成一个带有三个滑块的交互图表学生拖拽滑块时函数图像实时变化。教师不需要学 JavaScript不需要自己写可视化库一切都由 Pretext 包装好的组件自动完成。这是我目前认为 Pretext 相比 LaTeX 最具备“降维打击”能力的地方。6.2 集成在线作业系统如果你是数学老师可能听说过 WeBWorK一个开源的在线作业系统。Pretext 和 WeBWorK 有官方集成。在 XML 中写exercise标签并关联到 WeBWorK 题库学生提交的答案会自动送进 WeBWorK 评分系统成绩自动登记。这意味着什么你可以用 Pretext 写一份完整的电子教材每一节后面的练习题直接对接能自动评分、即时反馈的系统。学生从阅读到练习再到得到反馈整个流程都在同一个学习环境中完成。这在传统课程建设中是相当难实现的一体化体验。6.3 维护大型教材项目的经验最后聊一点项目工程化的经验。用 Pretext 维护大型教材时我有一个非常推荐的习惯一个章节至少拆成独立文件用xi:include包含到主文件中。比如main.ptx中book xi:include hrefchapters/chapter1.ptx / xi:include hrefchapters/chapter2.ptx / xi:include hrefchapters/chapter3.ptx / /book这样每个章节是独立文件多人协作时冲突更少单文件的行数也不会膨胀到编辑器都卡顿的地步。配合 Git 做版本管理每次修改的 diff 也清晰得多。我在最初维护时把所有内容写在一个main.ptx里到第 10 章后每次用编辑器打开都要等几秒钟后来拆分成章节文件体验立刻好多了。6.4 社区与生态Pretext 的社区规模不大但非常活跃。Github 上有PreTeXtBook的组织官方文档站pretextbook.org有从入门到高级的完整教程。社区维护了一批高质量的开源教材其中不少是美国大学的数学课程指定教材。直接下载这些教材的源码查看别人是怎么组织章节、怎么处理练习题、怎么设计交互式组件是我认为最高效的学习方式。最后说点实在的用 Pretext 这段时间我对“排版工具”这件事的认知有一些变化。以前我总觉得工具越强越好、控制力越精细越好现在则认为真正顺手的工具是让内容自己浮现出来、让形式自动退到后台的工具。Pretext 并不是没有缺点XML 标签冗长手写时容易被结构细节干扰自定义样式的自由度远不如直接写 LaTeX学习曲线相比 Markdown 陡了很多。但它解决的问题——一份内容多端分发长期维护可访问性——正是当前教育数字化环境下越来越多人会面对的痛点。如果这恰好也是你的痛点我建议你留出一个下午按这篇文章的步骤跑通第一个小项目然后再决定要不要把长期写作迁移过来。至少我自己的教材项目目前已经彻底从 LaTeX 切换到了 Pretext并且没有回退的打算。