跳到主要内容

章 14 · 篇 III · 实践

参与Postext贡献

如何加入Postext社区并为项目做贡献

更新于 2026-10-194分钟enescadefritptzhjaar

简单来说

Postext由一群志愿者共同开发,任何人都可以参与。你不一定要会编程。你也可以通过测试、撰写文档、翻译,或者分享你在设计和印刷方面的经验来帮忙。本页介绍团队的工作方式、最需要帮助的地方,以及怎样做出你的第一份贡献。最后介绍项目的长期目标。

一起打造Web一直缺少的书刊排版引擎。

Postext是一个由社区推动的开源项目。它要解决一个被忽视了几十年的问题:让Web也能做专业的书刊排版。这个目标很大,一个人做不完。

项目还年轻,但已经不是一张白纸:核心排版流水线、文档格式和配置系统都已发布。不过仍有很多设计决策悬而未决,现在加入的贡献者能够切实影响项目的走向。如果你一直在等一个合适的加入时机,就是现在。

参与贡献不一定要会编程。无论你是写代码、设计书刊版面、懂字体排印、做跨浏览器测试、写文档、翻译内容,还是只是对书刊内容在Web上应该怎样呈现有自己的想法,这里都有你的位置。

#为什么参与贡献

世界上每一个为出版物做开发的团队都面临同一个问题:CSS不是为书刊排版设计的。它原生不支持各栏齐底,不能防止段末孤行和段首孤行,不能让文字绕开障碍物排布,也不会放置脚注。每个团队都从零开始解决这些问题,做出脆弱的一次性方案,维护成本高,也无法共享。

Postext想改变这一点。它不是一个专有工具,而是一个共享的开放标准:一个高质量的排版引擎,全世界的出版社、杂志、报纸、图书平台和开发团队都可以采用,并在它的基础上继续开发。

这样的标准不可能由一个人或一家公司建成。它需要来自不同传统的字体排印师、PDF专家、无障碍专家、处理从右到左文字的开发者、为杂志排版的设计师,以及优化渲染性能的工程师。出版世界是多样的,服务它的工具背后也需要一个多样的社区。

#我们如何协作

所有协作都在GitHub上进行。没有私下的频道,没有封闭的邮件列表,也没有关起门来做的决定。一切都是公开的、可搜索的,任何人都可以参与。

  • Issues:用于报告缺陷、提出功能需求和跟踪具体任务。想做点什么,就从这里开始。
  • Pull Requests:用于提交代码贡献。写代码之前,先开一个issue讨论实现思路。
  • Discussions:用于交流想法、讨论设计、提问,以及所有不属于具体缺陷或任务的话题。这里适合把想法说出来慢慢推敲。

这样安排是有意为之:所有内容都集中在一处,任何人都能找到每个决策背后的来龙去脉,新加入的贡献者也能翻阅历史。

典型的贡献流程一个想法从Issue或Discussion开始,经过讨论后变成Pull Request,接受评审,最后合并。标为good first issue的Issue最适合新人入手。1Issue问题或想法2Discussion思路与设计3Pull Request代码评审4Merge合并到developgood first issue最佳入口
从想法到合并:四个阶段,全部在GitHub上公开进行。

#你可以参与的领域

项目需要各种不同的专长。以下是一些特别需要贡献的领域:

#代码与算法

  • 排版算法:Knuth-Plass两端对齐引擎、各栏齐底、最优段落断行、资源按类型编号,以及浮动体放置。
  • PDF生成:底层PDF构建、字体嵌入、色彩管理,以及单色图的资源字节处理。
  • 文本渲染:基于Canvas的渲染、SVG输出、单色SVG重新着色(diagramStyle.singleInk)、字体度量。
  • 性能优化:测量缓存层,用Rust编写并编译成WebAssembly的Knuth-Plass断行算法(rust/),以及让排版引擎保持足够快,每次调整尺寸都能实时重排。

#沙盒与界面

沙盒本身已经发展成一套相当完整的React界面:有带交互式表格编辑器、可上传图片和SVG的资源面板,有字体面板,有页面模板和漫画页的编辑器,还有版面设计面板,它的各组设置覆盖了引擎的各个部分。它的控件基于Base UI原语(packages/postext-sandbox/src/ui/)构建,并用axe-core和项目自己的检查按WCAG 2.2 AAA级标准检查,所以新控件应当复用这些原语,并保证每个字段的名称取自它的标签、说明取自它的帮助文字。所有界面文字都遵循严格的国际化约定:每个标签都要接入沙盒包、Web应用的标签桥接文件,以及十种语言各自的文案目录。如果你做前端或用户体验方面的工作,就会落在这一块。

#设计与排印

  • 书刊设计经验:如果你排过杂志、报纸或图书,你清楚什么样的版面行得通、什么样的行不通,这种经验非常宝贵,而且不需要写代码。
  • 字体排印传统:项目应当尊重不同语言和书写系统的字体排印惯例,而不只照顾拉丁文字。

#文档与社区

  • 文档:改进、扩充和维护文档。一个项目是被人采用还是被放弃,清晰的文档往往是分水岭。
  • 翻译:文档和网站共有十种语言:英语、西班牙语、加泰罗尼亚语、法语、德语、意大利语、巴西葡萄牙语、简体中文、日语和阿拉伯语。欢迎增加更多语言,也欢迎审校现有的语言。
  • 测试:在不同浏览器、操作系统和边界情况下测试。找出会出问题的版面,和构建能正常工作的版面一样有价值。

#格式与模式设计

格式已经不是一张白纸:::resource块、:ref行内引用,以及tableStyle、captionStyle和diagramStyle配置部分都已发布。现在的工作是在不破坏既有格式的前提下继续演进它:

  • 文档语法:旁注仍是悬而未决的问题,它既是技术问题,也同样是设计问题。
  • 配置模式:随着系统增长,既要让它对专业人士足够强大,又要让新手用起来足够简单。
你可以参与的领域一览四个象限,每个都有具体例子:代码与沙盒界面、设计与排印、文档与社区、格式与模式。postext代码与沙盒界面Knuth-Plass与浮动体PDF与渲染测量缓存沙盒界面与国际化设计与排印书刊设计字体排印传统杂志与报纸非拉丁文字文档与社区改进文档翻译跨浏览器测试帮助新人入门格式与模式::resource与:ref指令配置模式脚注与旁注交叉引用
不必动代码:在很多方面,一份贡献都能带来实实在在的改变。

#开始上手

实际的环境搭建(克隆仓库、安装依赖、运行测试)写在CONTRIBUTING.md里。具体步骤请先看那份文档。

环境搭好之后,可以做三件具体的事,投入由轻到重:

  1. 在Discussions里做个自我介绍:说说你在做什么、为什么来到这里。问题再基础也没关系,这也是让社区知道你来了的最快方式。
  2. 领一个good first issue:这些issue经过挑选,是切实可行的入门任务,不需要事先了解不为人知的历史背景。
  3. 把文档翻译成一种新语言,或者审校一种:目前文档有十种语言。每增加一种语言,就能让读不懂其他语言的读者读到它。

如果你打算写代码,先开一个issue讨论实现思路。这样可以避免重复劳动,事先简单沟通一下也能节省大家的时间。

每个源文件保持在约600行以内,每个文件夹保持在约25个源文件以内:超出的模块改为同名文件夹,原文件留作重新导出它的门面。CI用node scripts/source-size.mjs --check检查这些限制(见CONTRIBUTING.md中的Code Layout)。

#接下来读什么

动手之前,先熟悉一下整体情况:

  • 架构:排版流水线如何组织,各个子系统位于何处。
  • 文档格式:贡献者要扩展的增强Markdown语法。
  • 沙盒:一个试验场,大多数改动在这里最容易看到和测试。

#社区

Postext还处在早期,正因如此,现在这个时刻才格外特别。现在加入的贡献者不只是在写代码,也在塑造项目的约定、优先级和文化。

项目看重的是:

  • 深思熟虑的设计胜过速度。把抽象做对,比快速发布更重要。字体排印经过了几个世纪的打磨,我们也可以花时间把它做对。
  • 清晰胜过巧妙。易读、易于推理的代码,比炫技却晦涩的代码更有价值。
  • 协作胜过地盘。代码库的任何部分都不归某个人所有。想法按其本身的价值评判,而不是看由谁提出。

所有贡献者都会得到认可。这个项目之所以存在,是因为有人愿意花时间让它变得更好。

#愿景

Postext的目标是成为Web上书刊内容的标准排版引擎:出版社、杂志、报纸和图书平台需要专业的字体排印时,首先想到的就是它。

如果你从事出版开发,一直独自解决这些排版问题,现在就邀请你和大家一起,一次把它们真正解决好。