1. 排版引擎这条赛道PreTeXt到底站在哪做技术写作这些年我折腾过的排版工具不算少。从早期用Word硬排到后来切到LaTeX再到这几年被Typst种草几乎是每个工具出来都要试一遍。但我最近花时间最多的反而是很多人没怎么听过的PreTeXt。这个引擎最吸引我的地方是它走了一条和主流完全不同的路线——你写的不是排版命令而是内容本身的结构。你告诉它这是一个定理、那是一段解题过程、这里是思考题然后让系统决定最终在网页上、PDF里、电子书里长什么样。PreTeXt的前身是MathBook XML最早由南卡罗来纳大学等高校的数学教育项目推动目的是写开源数学教材。后来项目范围扩展从单纯的数学内容变成了通用的文本排版引擎名字也改成了PreTeXt目前的定位是用于编写教科书和学术文档的结构化排版系统。它适合谁来用我觉得最典型的是要长期维护教材、讲义、技术手册或开源书籍的人。如果你只是写一篇短论文Typst和LaTeX可能更顺手但如果你要维护一份几百页、包含大量交叉引用、公式、习题和可访问性要求的出版物PreTeXt这套单源多格式方案的优势会非常明显。1.1 从MathBook XML说起PreTeXt的前世今生要理解PreTeXt最好先看一眼它的历史。它脱胎于MathBook XML这个项目最早服务于数学教材的数字化需求——教授们想把教材同时发布成网页版和印刷版但又不想维护两份内容。数学教材里的定理、例题、证明、习题这些元素非常结构化用普通的Word或Markdown很难表达清楚LaTeX虽然能排版得很漂亮但它是命令式的从源码倒推不出语义。MathBook XML的做法是给这些数学结构设计一套专门的XML标签。比如一个定理在源文件里就是theorem标签里面嵌套statement陈述和proof证明而不像LaTeX那样写\begin{theorem}。这样写出来的文件机器能理解人也能读懂而且可以从同一份源码生成网页和PDF。后来项目发现这套思路不仅仅适用于数学各种学科的教材、开放课程、技术书籍都有类似的结构化需求于是改名PreTeXt把适用范围从数学扩展到了更广泛的学术和技术出版场景。目前很多开放教育项目、大学课程讲义都在用它。它不是一个新引擎替代旧引擎的故事而是一个换个角度解决问题的故事——它本身不负责底层排版而是依赖LaTeX引擎生成高质量PDF真正的核心是内容建模和跨格式分发能力。1.2 和LaTeX、Typst、SILE的路线之争现在主流的排版工具大致分几个流派LaTeX是宏包式你写命令控制排版Typst是脚本式干净、快、编程能力强SILE是面向复杂排版场景的现代排印系统PreTeXt则是语义式——你不直接控制排版而是描述内容结构排版交给样式系统。我用一个比较生活化的类比来解释LaTeX和Typst像是指挥一支乐队你直接告诉每个乐手什么时候用什么力度演奏什么音符PreTeXt则像写剧本你只写清楚这是主角的对白、那是场景描写至于舞台调度、灯光效果那是导演的事。PreTeXt里的导演就是预置的样式系统和各种输出处理链。工具核心写法输出形态学习曲线数学支持无障碍支持典型用户LaTeX命令式以PDF为主陡峭极强一般学术论文作者Typst脚本式PDF优先网页需配合中等强一般新项目技术文档SILE命令式脚本PDF为主中等可通过插件一般排版发烧友PreTeXt语义式XMLHTML、PDF、EPUB、盲文等偏艺术品但上限高极强很强教材、学术著作者PreTeXt不去抢LaTeX和Typst原有的短文档场景它主攻的是大型结构化出版项目。这也解释了为什么它学习曲线不像Typst那么快出成果——敲几行代码就能出一个好看的PDF页面PreTeXt做不到。但如果你需要同一份内容在官网、印刷书、电子阅读器、甚至盲人触摸屏上都有良好表现那它就走在了所有工具前面。2. 核心设计拆解为什么语义化写作被低估我最初接触PreTeXt的时候也犯过嘀咕——为什么不直接用Markdown反正Markdown也是结构化的标签。真正深入了解之后才发现Markdown的结构化程度在复杂出版物面前太弱了。2.1 从排版命令到内容结构的范式转变Markdown里你最多用#表示标题、用**加粗**表示强调但你想表达这是一个定理的陈述这是它的证明过程Markdown做不不到这种程度的语义标记。PreTeXt的标签体系覆盖了教材、学术书需要的大部分场景theorem、lemma、corollary数学定理、引理、推论example、exercise、activity例题、习题、活动figure、table、listing图表、表格、代码清单crossref交叉引用自动维护章节编号和链接idx索引词条自动生成索引bib、references参考文献支持BibTeX数据导入这套标签体系带来的最大好处是自动化和一致性。你不需要自己记第3章第2节第5个例题的编号是3.2.5PreTeXt在编译时自动生成编号、自动处理交叉引用、自动生成目录和索引。对我这种经常要修改章节顺序的人来说这简直是救命——在LaTeX里一旦大改结构需要清理的辅助文件和各种引用就够头疼的了。另一个容易被低估的点是批量改版。比如你决定把所有注意框从浅黄色底改成灰色底在PreTeXt里只需要改一份CSS或者一个XSLT模板全局生效。但如果你维护的是几百页的手工排版源文件技术债会直接让你崩溃。这就是为什么PreTeXt特别适合内容要长期演进的项目。2.2 单源多输出一份源文件五种落点PreTeXt官方很早就明确了多输出目标目前支持这些格式输出目标底层技术典型用途HTML自带样式和可定制主题在线教程、课程主页PDF通过LaTeX引擎主要xelatex印刷版、打印版EPUB内置EPUB生成器电子书、移动阅读Braille转换到盲文ASCII视障读者Slides生成HTML幻灯片课堂教学、演示我第一次看到这个清单还挺震撼的。尤其盲文输出一个排版引擎把无障碍做到这种程度在开源社区里非常少见。Braille输出不仅仅是把文字翻译成盲文编码它会根据内容结构重新组织阅读顺序定理、证明、习题有专门的盲文标志数学公式也会转换成适合盲人阅读的线性形式。这种深度的无障碍支持不是加个alt属性就能做到的它需要从底层就理解内容结构。多输出还有一个被忽略的好处生成HTML版本之后你可以用浏览器自带的无障碍工具直接检查问题而且每生成一次HTML相当于跑了一遍全文档的链接检查——交叉引用是否有效、图片路径是否存在一目了然。这对大型文档的质量保障很有帮助。2.3 无障碍与可访问性设计提到无障碍我想多说几句。PreTeXt对可访问性的重视是贯彻到设计理念的。传统的LaTeX编译出的PDF虽然有文本层可以检索、复制但阅读顺序和数学公式的可访问性都比较差。屏幕阅读器面对一堆数学符号时经常只会念出一堆无法理解的希腊字母名称。PreTeXt既然能生成HTML和盲文说明内容模型里天然包含了语义结构这让它能够为不同阅读通道生成合理的结果。在实际操作中我用PreTeXt生成的HTML版本搭配NVDA做了简单测试。数学公式在HTML里通过MathJax渲染屏幕阅读器能逐步读出公式结构——先读分数再读分子、分母内容而不是噼里啪啦念十几个符号。这个体验对学习数学的视觉障碍学生来说价值无法估量。PreTeXt的HTML输出还可以附加aria-label、role等无障碍标记让内容导航更清晰。说实话如果你所在行业有严格的可访问性合规要求PreTeXt几乎是目前唯一能同时覆盖STEM内容和无障碍需求的成熟方案。3. 实操记录从装好到跑通第一个中文化文档理论说了不少这块我直接把自己从零开始跑通的过程记录下来。这次操作环境是macOSPython 3.11顺序基本就是你照着做就能跑成功的路径。3.1 环境准备CLI、LaTeX发行版与必备依赖PreTeXt的编译链分为两层第一层是PreTeXt CLI工具负责解析源文件、生成中间产物第二层是LaTeX引擎负责把PreTeXt生成的中间文件转成PDF。所以环境要装两样东西。# 安装PreTeXt CLI我用的是pip方式 python3 -m pip install pretext # 验证安装 pretext --versionLaTeX引擎我建议直接用TeX Live。macOS装MacTeXLinux装完整的texlive-fullWindows装MiKTeX或TeX Live均可。PDF编译默认走的是xelatex因为中文等非拉丁字符需要XeTeX的字库支持。# macOS上安装MacTeX体积比较大但省心 brew install --cask mactex装完之后还需要确认几个辅助工具是否存在。PreTeXt生成PDF时会调用latexmk来管理编译过程同时依赖若干LaTeX宏包比如fontspec、unicode-math、xcolor等。完整TeX发行版一般都已经自带这些但如果用的轻量安装很可能会缺。你可以用一条命令测试xelatex --version如果版本号能正常打印说明基础环境没问题。注意PreTeXt CLI本身是用Python写的后续样式处理还会调用一系列XSLT转换。这个过程不需要单独装XSLT引擎因为CLI已经把需要的运行时打包好了不需要额外折腾Java或者外部XSLT解释器这点比早期版本省心很多。3.2 创建项目pretext new 与项目目录结构用CLI创建新项目非常直接# 创建一个名为mybook的项目 pretext new mybook cd mybook tree -L 2生成的项目结构大概长这样mybook/ ├── project.ptx ├── source/ │ └── main.ptx ├── publication/ │ └── public.ptx └── output/ └── ...简单解释一下project.ptx是项目总配置文件声明了项目名、作者、默认语言、参与编译的文件等。source/main.ptx是文档主文件你写的所有内容都从这里开始。publication/public.ptx描述输出目标样式。想把PDF和HTML调成不同风格就在这里改。output/是编译产物的目录没事不用手翻。PreTeXt对XML的格式要求很严格——标签必须闭合、缩进不影响逻辑但影响可读性、属性值必须加引号。如果你之前用Markdown比较多刚开始会不太习惯这种还要替它担心标签闭合的状态不过用支持XML语法高亮的编辑器VS Code装XML插件即可体验会好很多。3.3 写一节数学教材并编译到HTML与PDF打开source/main.ptx默认会有一个文章模板。我直接把它替换成一小节带定理和习题的内容article xml:iddemo-intro xmlns:xihttp://www.w3.org/2001/XInclude titlePreTeXt 入门示例/title introduction p这是一个非常简单的示例演示如何用PreTeXt写一节带定理和习题的内容。/p /introduction section xml:idsec-first title第一个定理/title p在正式的数学教材里每个定理都有编号并且可以被后续内容引用。/p theorem xml:idthm-pythagoras title勾股定理/title statement p直角三角形的两条直角边的平方和等于斜边的平方。/p /statement /theorem exercise xml:idex-practice title练习/title statement p请证明上述定理在等腰直角三角形中成立。/p /statement /exercise /section /article然后分别编译HTML和PDF# 编译HTML版本 pretext build html # 编译PDF版本 pretext build pdf第一次跑PDF会比较慢因为要下载/加载字体和宏包缓存。编译完成后在output/html目录下就能直接打开HTML文件在output/pdf目录下能找到生成的PDF。我拿到第一批输出时特别在意两件事一是HTML页面里定理编号是不是自动生成的二是PDF里中文是否能正常渲染。实测结果让我比较满意——编号自动生成交叉引用正确中文在xelatex配合CJK字体下也显示正常。3.4 定制样式修改CSS与LaTeX选项如果你不想用默认外观可以在publication/public.ptx里配置。这个文件里你会发现类似这样的片段publication source directories sourcesource/source /directories /source html styleoptional.css/style jsoptional.js/js /html pdf latex-enginexelatex/latex-engine packages packagefontspec/package /packages /pdf /publicationHTML的样式定制最灵活直接在style标签里指定一个自定义CSS文件路径编译时会自动引入。PDF样式定制则需要通过LaTeX宏包和\setmainfont之类的命令处理。我的经验是如果只是日常调色优先改HTML的CSS效果好、反馈快如果目标是印刷版再花时间调LaTeX模板因为印刷版的页边距、字体、页眉页脚这些细节用CSS是控制不了的。PreTeXt官方文档在这方面写得比较细需要深入定制时直接对着文档查就行。4. 常见问题与避坑清单每个工具都有一些表面看不出来、踩过才知道的坑。PreTeXt也不例外我把自己遇到的高频问题整理了一份清单。4.1 安装阶段的高频报错错误现象可能原因解决方案No module named pretextpip安装后命令找不到确认Python环境用python3 -m pip重装检查PATHPDF编译时字体报错缺少CJK字体或指定字体不存在在publication文件中指定系统中存在的字体如Noto Serif CJK SClatexmk not foundTeX发行版安装不完整补装latexmkLinux可用apt install latexmkmacOS的MacTeX自带XSLT相关异常CLU版本与项目模板不匹配升级pip install -U pretext中文化乱码源文件编码不是UTF-8确保所有.ptx文件以UTF-8保存其中最烦人的是字体问题。PreTeXt对西文的支持开箱即用但中文PDF需要额外指定字体。我在publication文件里加上字体配置后问题就解决了pdf latex-enginexelatex/latex-engine packages packagefontspec/package /packages fonts font nameNotoSerifCJKsc familyserif / font nameNotoSansCJKsc familysans-serif / /fonts /pdf注意中文字体名在不同系统上书写方式可能不同比如Noto Serif CJK SC和NotoSerifCJKsc的写法在fontspec中解析会不一样。建议先用fc-listLinux/macOS或字体册查看准确的字体名称再填到配置里。这个步骤别看小能省下不少排查时间。4.2 中文与CJK排版实战中文排版有两个层面需要处理。第一个层面是字体的选择。PreTeXt编译PDF时经过LaTeX引擎默认字体并不包含汉字字形所以必须指定支持中文的字体。推荐用思源宋体Noto Serif CJK SC或思源黑体Noto Sans CJK SC开源、字形全、和PreTeXt的兼容性也好。第二个层面是排版习惯的差异。比如中文首行缩进、中文引号、段间距等。PreTeXt的默认样式是面向西文设计的直接编译中文文档标点和段落在观感上会有点怪。我自己会在CSS里补充少量规则比如对p设置text-indent: 2em或者调整行高。这些细节只有真正在中文场景下用的时候才会意识到。另外多提一句PreTeXt源文件是Unicode编码所以中文内容可以直接写在XML里不需要转义成实体编码。这在写讲义时非常省心尤其后端交叉引用和索引都能正常处理中文句子。4.3 公式、代码与图表的高级玩法PreTeXt的数学公式用LaTeX语法但与LaTeX不同它已经封装好了显示环境。例如equation tex\int_0^\infty e^{-x^2} dx \frac{\sqrt{\pi}}{2}/tex /equation编译HTML时公式会交给MathJax渲染编译PDF时会交给LaTeX原生的数学环境处理。也就是说你在源码里只需要写一份公式两个输出端各自处理。代码块的写法也挺讲究。例如listing xml:idpy-hello title一个很简单的Python程序/title program languagepython input ![CDATA[print(Hello, PreTeXt!)]] /input /program output pcHello, PreTeXt!/c/p /output /listing图表方面PreTeXt支持嵌入外部图片也支持Asymptote绘制矢量图。如果要用TikZ需要通过LaTeX包机制加进去稍微麻烦一点但官方文档有专门的例子。我的建议是能用外部图片就用外部图片毕竟写PreTeXt的核心是内容组织重型的绘图交给专门的工具就好。5. 我的使用心得与进阶方向如果你问我PreTeXt到底值不值得学我的回答是取决于你写什么。如果你写的是需要反复修订、多版本发布、兼顾在线浏览和印刷质感的教材级文档那它几乎是目前最省心的方案。维护一份源文件就能保持网页版、PDF版、电子书版高度一致不用再为网页版更新了但PDF忘同步这种问题操心。我个人在实际操作中感受最深的一点是结构纪律性。PreTeXt要求你先想清楚这个内容属于什么类型、和别的部分是什么关系再动手写。这种约束一开始会拖慢速度但当你维护的文档超过两百页、改动越来越频繁时它带来的回报非常显著。交叉引用、编号管理、索引自动生成这些能力帮你省掉的时间远比多写的标签多。再给后续想尝试的人几个建议第一次跑通不要贪多就拿一小节示例文档试试理解HTML和PDF两条编译链路各自的配置点。如果项目涉及大量数学公式重点体验一下交叉引用和定理编号自动管理这是PreTeXt最让人上瘾的地方。如果你有可访问性方面的要求直接把HTML输出作为主要交付形态之一无障碍支持是它区别于所有竞品的核心优势。版本管理方面PreTeXt源文件是纯文本XML非常适合用Git管理。我在实际使用中会配一个CI任务每次push自动执行pretext build html和pretext build pdf输出到制品库团队所有人都能随时拿到最新版。PreTeXt不是万能的重度的自由版式设计、海报、画册这些场景完全不归它管。但在结构化出版物这个赛道上它的思路非常值得学习——先建模再排版。如果你手上正好有内容多、结构强、更新频繁的文档项目花一个周末把PreTeXt跑通大概率会觉得这个引擎早就该被人看见了。