Contributing

Contributing to Postext

How to join the Postext community and contribute to the project

Generated from docs/contributing-en.mdx (updated 2026-09-24). Read it on postext.dev, where it is also available in Spanish, Catalan, Portuguese, French, German, Italian, Chinese, Japanese and Arabic. To change this page, edit the MDX and run pnpm wiki in apps/web.

In short

Postext is built by a community of volunteers, and anyone can help. You do not have to be a programmer. You can also help by testing, writing documentation, translating, or sharing what you know about design and printing. This page explains how the team works, where help is most needed and how to make your first contribution. It ends with the long-term goals of the project.

Building the editorial layout engine the web has never had — together.

Postext is a community-driven open-source project. It aims to solve a problem that has been ignored for decades: bringing professional editorial layout to the web. That is a large ambition, and it requires more than one person.

The project is young, but it is no longer a blank page: the core layout pipeline, the document format, and the configuration system have all shipped. Plenty of design decisions remain open, though, and contributors who join now have genuine influence on the direction the project takes. If you have been waiting for a good moment to join — this is it.

You do not need to be a programmer to contribute. Whether you write code, design editorial layouts, understand typography, test across browsers, write documentation, translate content, or simply have ideas about how editorial content should work on the web — there is a place for you here.

Why Contribute

Every editorial development shop in the world faces the same problem: CSS was not built for editorial layout. There is no native support for column balancing, orphan and widow prevention, text flowing around obstacles, or footnote placement. Every team solves these problems from scratch, building fragile, one-off solutions that are expensive to maintain and impossible to share.

Postext aims to change that. Not as a proprietary tool, but as a shared open standard — a single, high-quality layout engine that publishers, magazines, newspapers, book platforms, and development teams worldwide can adopt and build upon.

That kind of standard cannot be built by one person or one company. It needs the perspective of typographers from different traditions, PDF specialists, accessibility experts, developers who work with right-to-left scripts, designers who lay out magazines, and engineers who optimize rendering performance. The diversity of the editorial world demands a diverse community behind the tool that serves it.

How We Work

All coordination happens on GitHub. There are no private channels, no closed mailing lists, no decisions made behind closed doors. Everything is public, searchable, and open to participation.

• Issues — for bug reports, feature requests, and specific tasks. If you want to work on something, start here.
• Pull Requests — for code contributions. Open an issue first to discuss the approach before writing code.
• Discussions — for ideas, design conversations, questions, and anything that is not a specific bug or task. This is the place to think out loud.

This is deliberate: when everything lives in one place, anyone can find the context behind any decision, and new contributors can read the history.

Figure: A typical contribution flow An idea starts as an Issue or Discussion, gets discussed, becomes a Pull Request that is reviewed, and is finally merged. Issues labelled good first issue are the entry point for newcomers.

From idea to merge: four stages, all public on GitHub.

Areas Where You Can Help

The project needs many different kinds of expertise. Here are some areas where contributions are especially valuable:

Code and algorithms

• Typographic layout algorithms — the Knuth-Plass justification engine, column balancing, optimal paragraph breaking, typed resource numbering, and float placement.
• PDF generation — low-level PDF construction, font embedding, color management, and resource byte handling for single-ink figures.
• Text rendering — canvas-based rendering, SVG output, single-ink SVG recoloring (diagramStyle.singleInk), font metrics.
• Performance optimization — the measurement cache layer, and keeping the layout engine fast enough for real-time use on every resize.

Sandbox and UI

The sandbox has grown into a substantial React surface in its own right: a Resources panel with an interactive table editor and image/SVG upload, a fonts panel, and a Design panel whose twelve groups cover every corner of the engine. Its controls are built on Base UI primitives (packages/postext-sandbox/src/ui/) and checked with axe-core for WCAG 2.1 AA, so new controls should reuse them and keep every field named by its label and described by its help text. Every UI string follows a strict i18n convention, wired through labels across five files spanning the sandbox package and the web app's locale catalogs. If you contribute frontend or UX work, this is where it lands.

Design and typography

• Editorial design expertise — if you have experience laying out magazines, newspapers, or books, your knowledge of what makes a layout work (or fail) is invaluable — no code required.
• Typographic traditions — the project should respect typographic conventions from different languages and writing systems, not just Latin scripts.

Documentation and community

• Documentation — improving, expanding, and maintaining the docs. Clear documentation is what makes the difference between a project that people can adopt and one they abandon.
• Translations — the documentation is currently bilingual (English and Spanish). More languages are welcome.
• Testing — testing across browsers, operating systems, and edge cases. Finding the layouts that break is just as valuable as building the ones that work.

Format and schema design

The format is no longer a blank slate: ::resource blocks, :ref inline references, and the tableStyle, captionStyle, and diagramStyle configuration sections have all shipped. The work now is evolving an established format without breaking it:

• Document grammar — margin notes and cross-references beyond resources are still open questions, each as much a design problem as a technical one.
• Configuration schema — keeping the system powerful enough for professionals and simple enough for newcomers as it grows.

Figure: Where you can help, at a glance Four quadrants with concrete examples in each: code and the sandbox UI, design and typography, documentation and community, format and schema.

No need to touch code: a contribution makes a real difference on many fronts.

Getting Started

The practical setup — cloning the repo, installing dependencies, running tests — is documented in CONTRIBUTING.md. Start there for the mechanical steps.

Once you are set up, three concrete actions, from lightest to heaviest commitment:

1. Introduce yourself in Discussions — say what you work on and what brought you here. No question is too basic, and it is the fastest way for the community to know you have arrived.
2. Pick up a good first issue — curated to be a realistic entry point, with no hidden historical context required.
3. Translate the docs into a new language — today the documentation is in English and Spanish. Any third language is a gift for readers who are currently left out.

If you plan to write code, open an issue first to discuss the approach — it avoids duplicate work, and a quick conversation upfront saves everyone time.

What to read next

To get your bearings before diving in:

• Architecture — how the layout pipeline is structured and where each subsystem lives.
• Document format — the enriched markdown grammar contributors extend.
• Sandbox — the playground where most changes are easiest to see and test.

The Community

Postext is still early — and that is precisely what makes this moment special. Contributors who join now are not just writing code; they are shaping the conventions, the priorities, and the culture.

The project values:

• Thoughtful design over speed. Getting the abstractions right matters more than shipping fast. Typography has been refined over centuries; we can take the time to get it right.
• Clarity over cleverness. Code that is easy to read and reason about is worth more than code that is impressive but opaque.
• Collaboration over territory. No one owns a part of the codebase. Ideas are evaluated on their merit, not on who proposed them.

All contributors are recognized. This project exists because people choose to spend their time making it better.

Vision

Postext aims to become the standard layout engine for editorial content on the web — the tool that publishers, magazines, newspapers, and book platforms reach for when they need professional typography.

If you work in editorial development and have been solving these layout problems alone, this is your invitation to solve them once, properly, with others.