# Postext
[](https://www.npmjs.com/package/postext)
[](https://github.com/drnachio/postext/actions/workflows/ci.yml?query=branch%3Amain)
**A programmable typesetter for the web.**
🌐 **Website:** [postext.dev](https://postext.dev/) · 📖 **Documentation:** [postext.dev/en/docs](https://postext.dev/en/docs) · 💬 **Community:** [Discord](https://discord.gg/CSzm6hr8YD)
Postext is a layout engine that bridges the centuries-old craft of print typesetting and the modern web. It takes semantic content — enriched markdown with referenced resources — and applies professional editorial layout rules to produce publication-grade output for HTML, PDF and EPUB.
Built on top of [`@chenglou/pretext`](https://github.com/chenglou/pretext) for DOM-free text measurement.
---
## How It Works
```
Enriched Markdown Postext engine Output
───────────────── ───────────────────────── ─────────────
┌────────────────────────┐
# Heading │ │ HTML + CSS
Paragraph text... │ 1. Parse & structure │ ┌─► (web rendering)
More text with a ───► │ 2. Measure (pretext) │ ───┤
:ref{id="fig"} and │ 3. Apply layout rules │ └─► PDF
a $formula$. │ 4. Compute geometry │ (print rendering)
│ │
└────────────────────────┘
▲
Configuration files
(columns, rules, spacing)
```
1. **Input.** Enriched markdown with referenced resources: images, tables, figures, formulas, pull quotes. The content is semantic, not visual — it describes *what* to present, not *how*.
2. **Engine.** postext parses the content structure, calls pretext for pixel-perfect text measurement without touching the DOM, then runs the layout algorithm: column balancing, resource placement, typographic quality rules, reference systems. All driven by configuration files.
3. **Output.** Format-agnostic layout geometry — precise coordinates and dimensions for every element. Renderers translate this geometry to the target format: canvas for page images, HTML/CSS for the web, PDF for print, EPUB 3 for e-book readers, and a 3D book in the browser (Folio).
---
## Why postext?
### The gap between print and web
A professional typesetter — the person who lays out a magazine, a newspaper, or a book — applies dozens of rules that have been refined over centuries:
- No orphans (a single line of a paragraph stranded at the top of a column).
- No widows (a single line of a paragraph left behind at the bottom).
- Balanced columns (roughly equal height across columns on a spread).
- Text flowing around figures, pull quotes, and inset images.
- Proper placement of footnotes at the bottom of the column where they are referenced.
- Margin notes aligned with the paragraph that cites them.
- Consistent and deliberate spacing around headings, block quotes, and figures.
- Hyphenation that avoids rivers and excessive rag.
CSS gives you almost none of this.
`column-count` exists but is fragile — there is no control over resource placement within columns, no overflow awareness, and no cross-column orphan/widow prevention. There is no native concept of "flow text around an arbitrarily positioned obstacle." Multi-column editorial layouts on the web remain essentially hand-crafted, usually as static designs that break on different screen sizes.
The web has had responsive layout (flexbox, grid) for over a decade. What it has never had is responsive *editorial* layout — the kind where content reflows intelligently through columns, around images, past footnotes, obeying the rules that make text *pleasant to read*.
### A decade of trying
This problem is not new. The [Content First](https://medium.com/binpar/el-arte-de-maquetar-para-ser-le%C3%ADdo-933be57cb293) project, started around 2014, was an early attempt to bring editorial layout quality to the web. I built column-based layouts, experimented with text flow algorithms, and ran into the same wall repeatedly: **you cannot make good layout decisions without knowing exactly how much space text will occupy.**
DOM-based measurement is expensive. Every time you ask the browser "how tall is this paragraph at this width?", you trigger a layout reflow. Do this hundreds of times for a complex layout and the page becomes unusable. I needed a way to measure text that was fast enough to run speculatively — trying different layouts, different column widths, different break points — without blocking the main thread.
### The missing piece
In 2025, Cheng Lou released [`pretext`](https://github.com/chenglou/pretext): a DOM-free text measurement library that is 300-600x faster than DOM measurement and pixel-perfect across Chrome, Safari, and Firefox. It uses canvas font metrics and pure arithmetic to compute text height and line breaks without ever touching the DOM.
With pretext, the core bottleneck disappears. You can measure thousands of text blocks in milliseconds. You can try ten different column configurations and pick the best one. You can run the full layout algorithm on every resize.
postext is what happens next.
---
## pretext + postext
The naming is intentional.
**pretext** is what happens *before* text is placed: measuring how much space it will need. DOM-free, canvas-based, operating on pure numbers.
**postext** is what happens *after* measurement: the editorial decisions. Given exact dimensions for every text block at any width, the engine decides where each element goes — which column, at what position, flowing around which resources, obeying which typographic rules.
```ts
import { prepare, layout } from '@chenglou/pretext';
import { buildDocument } from 'postext';
// pretext: measure (the "pre" work)
const prepared = prepare(paragraphText, '16px/1.5 Inter');
const { height } = layout(prepared, columnWidth, 24);
// => "This paragraph is 144px tall at this column width."
// postext: decide (the "post" work)
const doc = buildDocument(content, config);
// => "Put this paragraph in column 2, starting at y=320.
// Move the image to the top of column 3.
// Float the table to the top of page 3.
// Break here to avoid a widow."
```
pretext gives you the measurements. postext gives you the layout.
*pretext was created by [Cheng Lou](https://github.com/chenglou). postext builds on top of it.*
---
## Features
Everything below ships today in `postext` and its companion packages (`postext-pdf`, `postext-epub`, `postext-scorm`, `postext-folio`, `postext-citeproc`) and in the `postext` command line. A fuller list, with a link to the page that explains each part, is on the wiki's [Features](https://github.com/drnachio/postext/wiki/Features) page.
### Column-based layouts
- Single, double, and column-and-a-half layouts (`layoutType: 'single' | 'double' | 'oneAndHalf'`) with configurable gutter width, an optional column rule, mirrored margins, a page-wide baseline grid, and crop marks with bleed for print production.
- The column-and-a-half layout can turn its side column into a channel for figures, tables and callouts (`sideColumnRole: 'floats'`), placed at the outer edge of every page — the marginal column of a textbook — with side captions set level with their figure.
- `:::columns` switches the column count mid-page, `:::pagebreak` forces a break with parity control, `:::space` adds explicit vertical space, and `:::paper` changes the paper stock for a run of pages.
- Left- and right-bound books (`page.binding`), with the PDF asking viewers for right-to-left spreads, and vertical writing (`layout.writingMode: 'vertical-rl'`) for Chinese and Japanese books.
- Headings span a column or the full page, with parity-aware page breaks (`'odd'`, `'even'`, `'always-odd'`, …) for chapter openings.
### Column balancing
- Columns on a page end level: the engine closes each column's gap with the least visible lever — grid lines above headings, space after lists, room under top floats, and finally loosened or tightened paragraphs within word-spacing and tracking limits.
- Closing pages of a chapter balance too: the trailing band before a page-span box is levelled, short final columns are evened out, and a syllable is never stranded just to fill a column.
- Balancing converges chapter by chapter, so a chapter laid out alone and inside the whole book produce the same pages.
### Optimal justification
- Knuth-Plass optimal line breaking — whole paragraphs are broken globally, not greedily line by line. A Rust build of the breaker, compiled to WebAssembly, answers where WebAssembly is available, with the same breaks as the TypeScript one.
- TeX-pattern hyphenation in 8 locales (English, Spanish, French, German, Italian, Portuguese, Catalan with the IEC rule for *l·l*, Dutch); overlong words are divided by syllable, then by character.
- Orphan, widow, and runt control, plus keep-together rules (a heading with its first lines, a colon with the list it introduces).
### Resources as first-class citizens
- Bitmaps, SVGs, tables and videos are declared once alongside the content and incorporated by inline `:ref{id="…"}` references — the first reference floats the resource into the first free top or bottom band after it, spanning the column, the page, or the side channel.
- Floats of one numbering sequence never overtake each other; figures can be fitted to the page, and an explicit `::resource{id="…"}` embeds a resource inline.
- A picture may carry a safe area, the region that must stay in view: the engine crops it down to that area or lets it grow back to the whole picture, so a photo fills a short column or keeps an inline embed inside its column.
- Videos (YouTube, Vimeo or your own MP4/WebM file) are placed, captioned and numbered like pictures (*Video 1.1*). Print shows the poster frame with a play mark and a QR code that opens the video, and the PDF links the poster; the HTML viewer and EPUB play the video with the book's player options (no download button, loop, muted…).
- Typed first-reference numbering: `Figure` and `Table` built-ins (localized per document language) plus custom resource types, with configurable reference styles and caption prefixes.
- Tables taller than the page split between rows across as many pages as needed, repeating their header rows and a *(cont.)* caption; rowspans and group-head rows are never cut.
- Rotated tables (`placement.rotate`), cell fills, cell images (bitmap or SVG, aligned within the cell), in-cell lists, and inline colour swatches for legends.
- `diagramStyle.singleInk` recolors SVG diagrams to luminance-mapped tints of a single ink, so diagrams survive single-spot-colour printing.
### Callouts, pull quotes and marginal material
- `:::callout` boxes with named `calloutStyles`: fill, frame, radius, title, icon marker column, and their own paragraph typography — sidebars, key concepts, activities, pull quotes.
- Callouts can nest, float to the top or bottom of the page (`placement`), sit in the side channel, and split across columns and pages when they cannot be kept together, with a continuation that drops the title and icon.
- Named `paragraphStyles` applied with `:::paragraphs{style="…"}` for bibliographies, glossaries, notes and hanging-indent entries; tables and figures carry their own notes and source lines.
- `:::verse` blocks for poetry, including Arabic verse set as two hemistichs.
- Inline chips, `:chip[text]{style="…"}`: boxed words (word banks, keys, tags) that wrap as one unit, painted as real text in every backend.
### Exercises
- `:::exercise` blocks hold the questions and their answers in the Markdown, in twelve kinds: choice, true or false, gaps and word banks, matching, sorting, ordering, scrambles, words to mark, open questions with ruled writing areas, word searches, crosswords, and operations in columns (long division set as each country's schools set it).
- `exerciseStyles` decide how they print: the number badge, option labels, blanks, writing areas and activity icons. The solutions go after the exercise, upside down, at the end of the chapter or of the book, or nowhere, and the same text gives a teacher's edition with every answer filled in.
- In the HTML viewer and in both EPUB renditions the exercises can be answered on screen (typing, ticking, dragging to join or sort, marking words) and checked. Limits for a test (`exercises.digital`: checks per attempt, resets, when the solution shows, the pass mark) hold in the HTML, the EPUB and a SCORM package. See [Exercises](https://postext.dev/en/docs/exercises).
### Composed pages
- Fixed pages (a textbook spread, a workbook page, a magazine feature) set from page templates (`pageTemplates`): named frames, groups that share their space, a decoration and spreads, defined once in the configuration.
- In the Markdown a `::::page{template="…"}` fence sends each piece of content to a frame by name; positions and sizes never appear in the text, so a page is edited and translated as Markdown. A longer translation grows its box and pushes the boxes under it.
- Repeating layouts are declared once: a grid lays one card per item and goes on by whole rows, and `:::module` blocks stack bands of frames down the page, side by side or in rows, nested to any depth. Named frame looks (`frameLooks`) change a card's colours without a new style, and decoration can be drawn only on pages whose fence asks for it (`when` / `unless`).
- Connectors join frames with vector lines that follow them (straight, elbow, tree), leaders run from a label to a point of the picture and end in a ring or a bar, and path elements draw bars, ribbons and chevrons as vector shapes in every output.
- A frame that overflows tries, in order, its free space, its group, smaller pictures and smaller text, then continues on another page; what still does not fit is reported with proposals. Words on a map or a diagram are labels written in the Markdown and placed at anchor points of the picture.
- The Sandbox edits templates and frame styles, checks every edition, and moves text typed into an older configuration back into the Markdown (`moveTextToMarkdown`).
### Comics
- `:::page` cuts a page into panels with a split expression (slanted gutters, bleeds, spreads); each panel takes a picture without lettering and its lines of script.
- The engine letters the balloons, thoughts, captions and sound effects from that script in the book's language, so one set of pictures serves every edition. Strips (`:::strip`) for newspapers, right-to-left manga and Arabic editions, and Kindle Panel View in the fixed-layout EPUB.
### Notes, citations and indexes
- Footnotes (`[^id]`) set at the foot of the column that cites them, or gathered at the end of the chapter; numbered per chapter, through the book, per page or per column, in decimal, roman or circled numbers (①).
- Cross-references to headings, figures, tables and anchors (`{#id}`), clickable in the PDF.
- External links stay clickable in every output, and a printed page can show where they lead (`links.print`): the address in parentheses after the link text, or a numbered note set with the footnotes that prints the address, a QR code that opens it, or both. Short addresses, first-citation-only notes and the code's size, colour and error correction are settings; right-to-left and vertical books are handled.
- Citations in Pandoc syntax (`[@garcia2020, p. 33]`) formatted in a CSL style (APA, Chicago, MLA, IEEE, Vancouver, ISO 690, GB/T 7714, OSCOLA, …) with a generated bibliography, from BibTeX, CSL-JSON or CSL-YAML. With a note style each citation becomes a footnote. The styles are applied by `postext-citeproc`.
- A back-of-book index built from `:index[…]` marks and printed with `:::index`: sub-entries, sort keys, principal pages in bold and several indexes per book. The page numbers are found after layout, so they follow the text.
### Languages and scripts
- A document language (`locale`) drives hyphenation, built-in strings, numerals, text direction and the language tagged in the PDF.
- A book in several languages keeps **general settings** that every edition reads and, per language, an **override** with only the fields that language sets differently (the faces of its script, a label's wording), merged field by field (`configVersion` 21).
- Chinese (Simplified, Traditional, Hong Kong), horizontal or vertical: line breaking, punctuation widths and hanging punctuation, Han–Latin spacing, the character grid, emphasis dots, proper-name and book-title marks, ruby (pinyin, zhuyin) and warichu. See [Chinese layout](https://postext.dev/en/docs/chinese-layout).
- Arabic (Modern Standard and Classical): the bidirectional algorithm, right-bound books with right-to-left spreads, words shaped whole through HarfBuzz in the PDF, kashida justification instead of letter-spacing, vowel marks, Arabic-Indic digits and number words, and classical verse. See [Arabic layout](https://postext.dev/en/docs/arabic-layout).
- Japanese, vertical or horizontal, by JLReq and JIS X 4051: kinsoku, yakumono spacing and paragraph-start brackets, vertical forms and tate-chū-yoko, furigana (jukugo ruby, 1:2:1), sesame emphasis marks and side lines, kanbun kunten, Japanese counters (第一章), 行取り headings and 字下げ blocks, notes, a gojūon index with readings, SIST 02 citations and Aozora Bunko sources. See [Japanese layout](https://postext.dev/en/docs/japanese-layout).
### Books, parts and front matter
- Books laid out one chapter at a time with an engine `continuation`: page numbers, parity, heading and figure counters and open parts carry across chapters, or the whole book is built as one document.
- `:::part` divider pages with their own design, and part palettes that recolour the design and flow of every chapter in the part.
- Named `headingStyles` that govern a whole section — running heads, page geometry, body typography, palette — so front matter can live beside decimal-numbered chapters in one configuration.
- `:::toc` prints a table of contents fed by the book's outline, with leaders, numbers and page labels.
### Styling configuration
- `tableStyle` / `tableStyles` — table typography independent of body text, named variants picked with `table.styleId`, and a rounded outer frame.
- `captionStyle`, `chipStyles`, `calloutStyles`, `paragraphStyles`, `headingStyles` — every style is a named, reusable object.
- Color palettes let a whole document re-ink from one place.
- `figureStyle` sets the figures of each text style: old-style for running prose, lining for headings, tabular for table columns, proportional where they read best. The engine applies the font's OpenType features in the canvas, HTML, PDF, EPUB and command-line outputs; a face without them keeps its own figures.
- Design text and chips can be set as dotted letters for a child to trace, and repeated along a line — the tracing copies of a handwriting workbook stay live text.
### Math
- LaTeX math, inline (`$…$`) and display (`$$…$$`), rendered to crisp SVG via MathJax in every backend, loaded on demand (`await initMathEngine()`). MathJax ships pre-bundled, so it loads the same from a bundler, Node or a CDN.
### Music notation
- Music is written as text in the chapter, in a ` ```abc `, ` ```musicxml `, ` ```mei ` or ` ```humdrum ` fence, and engraved by [Verovio](https://www.verovio.org) at the width of its column. A long score is cut into systems that run on over columns and pages like lines of text, and `scoreStyle.minSystemsAtBreak` never leaves a system alone at a break.
- Music examples the text cites are `score` resources, numbered, captioned, floated and referenced like figures (*Example 3.2*), from inline notation or a MusicXML file exported from Dorico, Sibelius, Finale or MuseScore.
- `scoreStyle` and named `scoreStyles` set the staff size, the music font (Bravura, Leland, Petaluma, Leipzig, Gootville), the lyrics font, spacing, bar numbers and ink.
- Scores are vector paths in the Canvas, HTML and PDF (a tagged `Figure` with its alt text), inline SVG in a reflowable EPUB, and their notation fence in Word. The engraver loads only for books that have music. See [Music notation](https://postext.dev/en/docs/music).
### Headers & footers
- Design slots composed of text, rule, box, and image elements with precise placement, painted in array order and bounded to the trim box.
- Placeholders resolve page numbers, chapter numbers and titles, part titles, and document metadata at layout time.
- Page numbers in arabic, roman, letters, Chinese, Arabic-Indic and other styles, restarted with `:::numbering`, with PDF page labels that match the printed folios.
- Page-parity control — different designs for odd and even pages.
### Multi-format output
- **Canvas renderer.** Rasterize any page for previews and thumbnails (`renderPage`, `renderPageToCanvas`).
- **HTML renderer.** Precise absolutely-positioned markup; `renderToHtmlIndexed` returns a per-block index so viewers can patch only the DOM nodes that changed between builds.
- **PDF renderer** (`postext-pdf`). Print-ready output with document outlines, clickable cross-reference and web links (with QR codes for printed addresses), embedded custom fonts (woff2/woff/ttf/otf) with GPOS kerning, HarfBuzz shaping for Arabic, page labels, vector SVG figures (with optional PDF print masters), RGB, CMYK, or grayscale color spaces, and **tagged, accessible PDF/UA-1** output validated with veraPDF. `postext-pdf/worker` writes long books off the main thread.
- **EPUB 3 writer** (`postext-epub`). The whole book as an EPUB 3.3 file, written in the browser or in Node: a **fixed layout** (`pre-paginated`) that keeps every printed page with real, selectable text, or a **reflowable** book in semantic XHTML (paragraphs rebuilt from the lines, notes, figures and tables in reading order, print page markers) styled from the same configuration. Fonts embedded, with navigation, print page numbers, right-to-left books and accessibility metadata; validated with W3C EPUBCheck.
- **SCORM packages** (`postext-scorm`). A book, or the chapters and sections picked from it, as a SCORM 1.2 or SCORM 2004 package for a learning management system (Moodle, Canvas, Blackboard, …): fixed pages or reflowable text from the EPUB writer, a small player per SCO, and exercises that send their score, completion and pass or fail to the LMS (`renderToScorm`).
- **Print production.** PDF/X-1a and PDF/X-4 files (`print.standard`) with an ICC output profile (FOGRA, GRACoL, SWOP and IFRA profiles are bundled, or your own), every colour and RGB picture separated through it, black overprint and rich black, an ink limit, and a preflight that reports low-resolution pictures, thin rules, small text in several inks and text near the trim before the file is written. The Sandbox shows a print preview of the separated pages.
- **Word files** (`postext/word`). A `.docx` is read into chapters of Markdown, with its styles mapped to Postext styles and a quality report (`readDocx`, `analyzeDocx`, `wordToPostext`), and a book is written back in two variants: a **semantic** file built from real Word structures to edit (`semanticDocx`), and a **formatted** file whose pages match the PDF, columns, floats and fonts included (`formattedDocx`). Both carry an export map, so corrections made in Word come back to the exact place in the Markdown or the resources they belong to (`applyDocxEdits`). The Sandbox and the command line (`postext docx --variant`, `postext import-docx <file> <book>`) both import and export Word.
- **InDesign packages** (`postext/idml`). The laid-out pages as an IDML package for finishing a book in InDesign (`idmlDocument`): one page per spread, rules, boxes, paths and pictures (embedded or linked from `Links/`) as native page items, authored CMYK colours as process swatches, the text of each composed frame as one story under a paragraph style named after its box style (chained frames share one story), and chips with a form field as InDesign form fields. InDesign sets the text again with its own composer, so line breaks may differ; tables and maths are not written yet. The command line writes it with `postext idml`.
- **3D book viewer** (`postext-folio`). Spreads whose leaves curl in three.js, with real shadows, turned by hand or by key; a right-bound book lies mirrored. Pages are painted on demand, at the size they are shown, around the open spread only.
- **Web Worker.** `postext/worker` runs the pipeline off the main thread with last-wins cancellation, also loaded straight from esm.sh.
- **React.** `postext/react` shows a document's pages in a component; the main entry never loads React.
- **Format-agnostic core.** The engine computes geometry; renderers translate it.
### Sandbox
- A hosted editor at [postext.dev](https://postext.dev/en/sandbox): books of chapters, a Design panel that browses every setting in editorial terms (accessible, keyboard-first), a Resources panel, live Canvas / PDF / Folio (3D) / HTML previews with source ↔ preview sync, an EPUB 3 tab that writes, shows and downloads the book as an e-book (with its exercises answerable in the reader), a SCORM tab that packages the chapters and sections you pick for a learning platform, Word import and export, editors for page templates and comic pages, a Checks panel, permalinks to any page, and a phone layout.
- The Design panel edits every engine setting; `scripts/config-coverage.mjs --check` compares the configuration schema with the panel, the docs and the agent skill.
- A book holds an edition per language, each with its own title and pagination: the editions rail switches between them, the Design panel edits either the general settings or one language's override (each field shows which layer sets it), and the side-by-side view shows two editions of the whole book, kept on the same passage of text.
- Books travel as `.postext` bundles that carry their pagination, so an imported book opens already paginated.
- The same `.postext` files are created and opened from code with the `postext` package (`createBundle`, `openBundle`, `buildBundle`), so a book moves between the Sandbox, the agent skill and your own program.
- Showcase bundles — a magazine, literary editions (*Don Quijote*, an annotated *Paradise Lost*), an atlas, an exhibition catalogue, a physics textbook, a column-and-a-half biochemistry manual, the classic Chinese novel *Dream of the Red Chamber* (红楼梦), Natsume Sōseki's *Kokoro* (こころ) set vertically and *One Thousand and One Nights* in Arabic — plus a built-in guide to Postext that covers every feature, itself set as a book in every language of the site and checked page by page in each edition: Chinese and Japanese vertical, Arabic right to left.
### Cookbook
- 180 complete, copy-ready examples at [postext.dev/en/cookbook](https://postext.dev/en/cookbook) (*Recetario* in Spanish): each recipe is a real publication set with Postext — an opener, a book page with running heads, a data table, a songbook page, a print-ready PDF — grouped in chapters and searchable by feature, genre, level and output.
- Every recipe page shows the captured pages and the whole pen, with Copy, Open in CodePen, an `.html` download and, where it applies, the PDF; a write-up explains the method step by step, with excerpts of the real code, and the pitfalls. The same content is available as Markdown for agents (`/en/cookbook/<slug>.md`, and in `llms.txt`).
- Recipes live in [`cookbook/`](cookbook/README.md), one folder each (metadata, bilingual write-ups, the pen and its sample text); `pnpm cookbook new | dev | lint | capture` scaffolds, previews, checks and captures them against the released engine, and `pnpm cookbook sandbox` and `pnpm cookbook bench` check the captured books in the Sandbox's own layout and the composed pages under longer text.
### Website
- [postext.dev](https://postext.dev/) in English, Spanish, Catalan, French, German, Italian, Brazilian Portuguese, Simplified Chinese, Japanese and Arabic, built to WCAG 2.2 AAA, with a Markdown version of every page for agents (`<page>.md`, `llms.txt`) and [WebMCP](https://webmachinelearning.github.io/webmcp/) tools for an agent in the browser: on every page to search, read and open pages, and in the Sandbox to edit the book, change any setting, do anything the Settings panel does (rename or remove a style with everything that names it, apply a language's defaults, upload an ICC profile, save a laid page as a template), get any laid-out page as a JPEG and change again.
### Configuration-driven
- Every behavior above is driven by a single configuration object with sensible defaults — an empty config produces a well-typeset document, and each section (page, layout, body text, headings, lists, math, resource types, styles, parts, TOC, …) can be overridden independently.
### Agent skill: port existing publications
- **`postext-port`** teaches a coding agent (Claude Code, Codex, Cursor, Gemini CLI, Copilot, …) to turn an existing publication — a PDF, Word, PowerPoint, EPUB, HTML, InDesign (IDML), LaTeX or scanned source — into a Postext project that follows the original layout: measured config manifest, curated chapters, resources and fonts. Music textbooks, methods and songbooks bring their examples as MusicXML scores.
- It bundles verified references (document format, configuration, project format, per-source playbooks, the unusual cases solved in every preset) and scripts: type-role PDF extraction, figure and table cutting, pandoc/IDML converters, font and image tools, a linter, a headless renderer and page-by-page comparison.
- Install it with `npx skills add drnachio/postext --skill postext-port`, or in Claude Code with `/plugin marketplace add drnachio/postext` + `/plugin install postext@postext`. See [the Skill docs](https://postext.dev/en/docs/skill).
### Command line
- **`postext`** is one self-contained executable per system (macOS arm64 and x64, Linux x64, arm64 and musl, Windows x64): no installation, no runtime, no libraries. The engine, the PDF, EPUB, HTML and Word writers, the page painter (Skia), the default fonts and the ICC print profiles are inside. Every release attaches them to its [GitHub Release](https://github.com/drnachio/postext/releases/latest); [`readme.txt`](packages/postext-cli/bin/readme.txt) lists them, and `npx postext-cli` fetches the right one.
```bash
brew install drnachio/postext/postext # macOS, Linux (Homebrew)
scoop bucket add postext https://github.com/drnachio/scoop-postext # Windows (Scoop)
scoop install postext
```
- It reads a `.postext` bundle, an unpacked book folder or loose Markdown files, and writes a PDF (PDF/X and ICC profiles included), HTML, EPUB, one page or every page as PNG, JPEG or WebP, and Word; it also packs and unpacks bundles, imports `.docx`, describes a book and checks it. `postext build --watch` keeps the engine warm and rebuilds on every save.
- Made for scripts and agents: `--json` prints one report (outputs, pages, warnings with file and line, timings), exit codes are stable, `-o -` writes to stdout, and fonts a book does not carry are fetched once from Google Fonts and cached (`--offline` never fetches). Run `postext` with no arguments for the help.
- **From Python**: `pip install postext` ([`packages/postext-python`](packages/postext-python)) runs the same executable, downloaded on first use from the release of its version and checked against `SHA256SUMS` (`POSTEXT_BIN` points at one already installed). Every command is a function that returns the `--json` report as objects, warnings included, and raises on failure:
```python
import postext
report = postext.pdf("book.postext", out="book.pdf", set={"page.dpi": 300})
pdf = postext.pdf_bytes(open("book.postext", "rb").read())
```
---
## Project Structure
```
postext/
├── apps/
│ └── web/ # Next.js site: landing, docs, sandbox, cookbook
├── packages/
│ ├── postext/ # Core layout engine library
│ ├── postext-pdf/ # PDF rendering backend
│ ├── postext-folio/ # 3D book viewer (three.js)
│ ├── postext-epub/ # EPUB 3 writer (fixed layout and reflowable)
│ ├── postext-scorm/ # SCORM 1.2 / 2004 packages for learning platforms
│ ├── postext-citeproc/ # CSL citations and bibliographies (citeproc-js)
│ ├── postext-cli/ # Command line: self-contained executables (Bun)
│ ├── postext-python/ # Python package: pip install postext, drives the command line
│ ├── postext-sandbox/ # Interactive sandbox UI (controls + viewports)
│ └── typescript-config/ # Shared TypeScript configurations
├── docs/ # MDX documentation, <topic>-<locale>.mdx in ten locales
├── cookbook/ # Cookbook recipes (one folder each), registries and pen kit
├── plugins/postext/ # Agent skill `postext-port` (Claude Code plugin + skills.sh)
├── rust/ # Knuth-Plass line breaker in Rust, compiled to WebAssembly
├── .claude-plugin/ # Claude Code plugin marketplace manifest
├── turbo.json # Turborepo task pipeline
├── pnpm-workspace.yaml # pnpm workspace definition
└── package.json # Root scripts (delegate to turbo)
```
| Package | Purpose |
|---|---|
| `packages/postext` | The core library. Semantic content in, layout geometry out. Zero DOM dependencies. Published to npm as `postext`. |
| `packages/postext-pdf` | The PDF backend: renders the layout geometry to print-ready, tagged PDF (outlines, links, font embedding, color spaces). Published to npm as `postext-pdf`. |
| `packages/postext-folio` | The 3D book viewer: a laid-out document (or any page images) as spreads whose leaves turn in three.js. Published to npm as `postext-folio`. |
| `packages/postext-epub` | The EPUB 3 writer: a laid-out book as a fixed-layout or reflowable EPUB, plus `readEpub` for viewers. Published to npm as `postext-epub`. |
| `packages/postext-scorm` | The SCORM writer: a book, or the chapters and sections picked from it, as a SCORM 1.2 or 2004 package whose exercises report to the LMS (`renderToScorm`). Published to npm as `postext-scorm`. |
| `packages/postext-citeproc` | The citation engine: formats Pandoc-syntax citations with citeproc-js and builds the bibliography, with 20 bundled CSL styles and 14 CSL locales. Published to npm as `postext-citeproc`. |
| `packages/postext-cli` | The command line: `postext pdf`, `html`, `epub`, `image(s)`, `docx`, `import-docx`, `pack`, `unpack`, `info`, `check` and `build --watch`, compiled with Bun into a self-contained executable for each system (`pnpm --filter postext-cli build:bin` writes them to `bin/`). Released as GitHub Release assets, on npm as `postext-cli`, in the Homebrew tap [`drnachio/homebrew-postext`](https://github.com/drnachio/homebrew-postext) and in the Scoop bucket [`drnachio/scoop-postext`](https://github.com/drnachio/scoop-postext). |
| `packages/postext-python` | The Python package `postext` on PyPI: a pure-Python wheel with a typed function per command (`postext.pdf`, `check`, `info`…) that runs the command line with `--json` and returns its report as dataclasses. It downloads the executable of its version from the GitHub Release on first use. |
| `packages/postext-sandbox` | The interactive sandbox UI — configuration controls and live Canvas/PDF/Folio/HTML/EPUB viewports and the SCORM export — embedded by the web app. |
| `apps/web` | Next.js 16 + Tailwind CSS 4 application: the documentation site, landing page, hosted sandbox and cookbook at [postext.dev](https://postext.dev), in ten languages. |
| `packages/typescript-config` | Shared strict TypeScript configuration across all packages. |
Documentation lives in the top-level `docs/` folder as one MDX file per topic and locale (`<topic>-<locale>.mdx`, in `en`, `es`, `ca`, `fr`, `de`, `it`, `pt`, `zh`, `ja` and `ar`), rendered by `apps/web`. The doc pages of the [GitHub wiki](https://github.com/drnachio/postext/wiki) are generated from the English files (`pnpm wiki` in `apps/web`).
**Tech stack:** pnpm workspaces, Turborepo 2, TypeScript 6, ESM-only, Node.js 20+, Next.js 16, Tailwind CSS 4, Bun for the command line, Rust for the WebAssembly line breaker.
---
## Getting Started
### Prerequisites
- [Node.js](https://nodejs.org/) >= 20
- [pnpm](https://pnpm.io/) 12 (the version in `packageManager`; `corepack enable` installs it)
### Installation
```bash
git clone https://github.com/drnachio/postext.git
cd postext
pnpm install
```
### Development
```bash
# Start all packages in dev mode (library watch + Next.js dev server)
pnpm dev
# Build all packages
pnpm build
# Lint all packages
pnpm lint
# Type-check all packages
pnpm check-types
# Run every package's tests (`pnpm test:changed` for only what you touched)
pnpm test
```
Turborepo handles the dependency graph: `packages/postext` builds first, then `apps/web` picks up the changes. In dev mode, the library recompiles on save and the Next.js app hot-reloads.
### Using postext in your project
```bash
npm install postext
# or
pnpm add postext
```
The libraries are also on [JSR](https://jsr.io/@postext) as `@postext/postext`, `@postext/pdf`, `@postext/epub`, `@postext/folio`, `@postext/citeproc` and `@postext/scorm` (`deno add jsr:@postext/postext`, `pnpm add jsr:@postext/postext`, `npx jsr add @postext/postext`), and are imported under those names. With `npx jsr add` or `bunx jsr add`, a book that cites needs the engine imported as `@jsr/postext__postext`, or its citations stay unformatted. Outside a browser the engine needs an `OffscreenCanvas`, for instance from `@napi-rs/canvas`. See [Programmatic usage › Installing](https://postext.dev/en/docs/configuration-programmatic-usage#installing).
`buildDocument` takes content plus a configuration object and returns the laid-out document — plain layout geometry, not framework components — which any backend can then render. The quickest path is the HTML string renderer:
```ts
import { buildDocument, renderToHtml } from 'postext';
const doc = buildDocument(
{ markdown: '# Hello\n\nThis is postext.' },
{
page: { sizePreset: '17x24' },
layout: { layoutType: 'double', gutterWidth: { value: 0.75, unit: 'cm' } },
bodyText: { fontFamily: 'EB Garamond', fontSize: { value: 8, unit: 'pt' } },
// ...see docs/configuration for the full reference
},
);
// Render to an HTML string (in-browser viewer)
const html = renderToHtml(doc);
// …or rasterize to canvas — see renderPage / renderPageToCanvas.
```
To leaf through the result as a book in 3D, hand the same document to `postext-folio` (`npm install postext-folio three`):
```ts
import { createFolioFromDocument } from 'postext-folio';
createFolioFromDocument(document.getElementById('book')!, doc);
```
To publish it as an e-book, hand the book's chapters to `postext-epub` (`npm install postext-epub`):
```ts
import { renderToEpub } from 'postext-epub';
const epub = await renderToEpub([doc], {
layout: 'reflowable', // or 'fixed': every printed page as it is
metadata: { title: 'Hello', language: 'en' },
});
```
Documents that cite (`[@key]`) need the citation engine from `postext-citeproc` (`npm install postext-citeproc`). Register it once before laying out:
```ts
import 'postext-citeproc/register';
```
### Asynchronous layout in a Web Worker (recommended for UIs)
For interactive integrations — live previews, editors, anything that rebuilds
the document on every keystroke or resize — run the pipeline off the main
thread via the dedicated worker entry point. This keeps the UI responsive,
gives you last-wins cancellation via `AbortSignal`, and ships fonts into the
worker as transferable `ArrayBuffer`s so measurement stays pixel-identical to
the main-thread build:
```ts
import { createLayoutWorker } from 'postext/worker';
const layout = createLayoutWorker();
// Register fonts once per family (woff2/ttf ArrayBuffers are transferred).
await layout.registerFonts(fontPayloads);
const controller = new AbortController();
const vdt = await layout.build(content, config, { signal: controller.signal });
// Call controller.abort() to supersede an in-flight build — the worker stops
// the current pipeline and the pending promise rejects with AbortError.
layout.dispose();
```
The full async integration pattern (font shipping, cancellation, measurement
cache reuse) is documented under
[Running layout in a Web Worker](https://postext.dev/en/docs/configuration-programmatic-usage#running-layout-in-a-web-worker).
For an end-to-end HTML-viewer integration (multi-column, resize-aware, Shadow DOM),
see [Integrating the HTML viewer](https://postext.dev/en/docs/configuration-html-folio-epub#integrating-the-html-viewer).
---
## Roadmap
Every milestone of the original roadmap is closed. Postext now typesets full books — textbooks, magazines, literary editions and catalogues — end to end, from enriched markdown to accessible, print-ready PDF, EPUB 3, SCORM packages and a 3D book. Work continues in programmes tracked as GitHub issues; the wiki's [Roadmap](https://github.com/drnachio/postext/wiki/Roadmap) page follows them.
### Phase 1: Foundation ✅
- [x] Core layout data structures (columns, blocks, inline resources, break points)
- [x] Integration with `@chenglou/pretext` for text measurement
- [x] Enriched markdown input format definition and parser
- [x] Basic single-column layout with paragraph placement
- [x] Configuration file schema (first draft)
### Phase 2: Editorial Layout ✅
- [x] Multi-column layout engine
- [x] Column balancing algorithm (level columns and closing pages, chapter-wise convergence)
- [x] Resource placement within columns (images, figures, tables — floats with column, page or side-channel span)
- [x] Text flow around obstacles (floats, callout boxes, side channel and side captions)
- [x] Orphan and widow prevention
- [x] Keep-together rules (headings + first paragraph, colons + lists)
### Phase 3: Professional Typography ✅
- [x] Hyphenation dictionary integration (TeX patterns, 8 locales)
- [x] Typed resource numbering and cross-references (figures, tables, custom types)
- [x] LaTeX math rendering (inline and display, MathJax SVG)
- [x] Custom font loading and embedding (woff2/woff/ttf/otf)
- [x] Notes (footnotes, resource and table notes, note paragraph styles, marginal glosses in the side channel)
- [x] Pull quotes and margin notes (callout styles, side-channel boxes)
- [x] Fine-grained spacing rules (configurable spacing scale)
- [x] Rag optimization
- [x] Configuration file format finalization
### Phase 4: Output Targets ✅
- [x] Web renderer (HTML/CSS with precise positioning)
- [x] PDF renderer (outlines, clickable cross-reference links, RGB/CMYK/grayscale)
- [x] Interactive playground in `apps/web`
- [x] Visual configuration editor (stretch goal)
- [x] Asynchronous layout worker (off-main-thread `buildDocument` with last-wins cancellation)
### Beyond the original plan ✅
- [x] Books, chapters and parts with cross-chapter continuation
- [x] Front matter, heading styles and a table of contents built from the outline
- [x] Tables split across pages, rotated tables, cell images and fills
- [x] Nested, floated and splittable callouts; inline chips
- [x] Tagged, accessible PDF/UA-1 output and vector figures in PDF
- [x] `.postext` book bundles and bilingual showcase presets
- [x] EPUB 3 output, fixed layout and reflowable, checked with W3C EPUBCheck
- [x] Folio, the 3D book viewer
- [x] Footnotes ([#162](https://github.com/drnachio/postext/issues/162)), CSL citations and bibliographies (`postext-citeproc`), a back-of-book index ([#165](https://github.com/drnachio/postext/issues/165))
- [x] Chinese typesetting, horizontal and vertical ([#203](https://github.com/drnachio/postext/issues/203))
- [x] Arabic typesetting, Modern Standard and Classical
- [x] Japanese typesetting, vertical and horizontal ([#440](https://github.com/drnachio/postext/issues/440))
- [x] Pictures with a safe area ([#442](https://github.com/drnachio/postext/issues/442)) and video resources: poster, play mark and QR code in print, players in HTML and EPUB ([#460](https://github.com/drnachio/postext/issues/460))
- [x] The Cookbook, the showcase books and the built-in guide in every language of the site
- [x] The `postext-port` agent skill
- [x] The website in ten languages, at WCAG 2.2 AAA
- [x] Composed pages: page templates with frames filled from the Markdown ([#846](https://github.com/drnachio/postext/issues/846)), then modules, repeating grids, connectors and vector shapes ([#1051](https://github.com/drnachio/postext/issues/1051), [#1086](https://github.com/drnachio/postext/issues/1086))
- [x] Comics, manga and newspaper strips lettered by the engine ([#553](https://github.com/drnachio/postext/issues/553))
- [x] Print production: ICC profiles, PDF/X and preflight ([#609](https://github.com/drnachio/postext/issues/609))
- [x] Word import and export ([#599](https://github.com/drnachio/postext/issues/599))
- [x] The `postext` command line ([#617](https://github.com/drnachio/postext/issues/617)) and WebMCP tools for agents in the browser
- [x] The Rust line breaker in WebAssembly and a faster whole-book layout ([#779](https://github.com/drnachio/postext/issues/779))
- [x] Music notation engraved by Verovio: scores in the text and numbered music examples ([#1178](https://github.com/drnachio/postext/issues/1178))
- [x] General settings with per-language overrides for books in several languages ([#1209](https://github.com/drnachio/postext/issues/1209))
- [x] Textbook and workbook exercises, printed and answerable on screen ([#1235](https://github.com/drnachio/postext/issues/1235)), and SCORM packages for learning platforms ([#1270](https://github.com/drnachio/postext/issues/1270))
- [x] Figure styles per text style: old-style, lining, tabular, proportional ([#1237](https://github.com/drnachio/postext/issues/1237))
- [x] Printed link addresses: inline URLs, link notes and QR codes ([#1302](https://github.com/drnachio/postext/issues/1302))
What comes next is driven by the community: open an issue that describes the publication you are trying to set and where Postext falls short.
---
## Contributing
Postext is a young open-source project, and the community around it is only starting to form. New collaborators are always welcome. The goal is to build a shared standard that any editorial development team worldwide can adopt — a common foundation for professional web typography.
If you want to contribute code, please open an issue first to discuss the approach. This helps avoid duplicate work and ensures alignment with the project direction. Follow existing code style and TypeScript strict mode. A source file stays under about 600 lines and a folder under about 25 files; CI checks it with `node scripts/source-size.mjs --check` (see [CONTRIBUTING.md](CONTRIBUTING.md)).
The project especially welcomes people with experience in:
- **Typographic layout algorithms** (Knuth-Plass, column balancing, optimal paragraph breaking)
- **PDF generation** (low-level PDF construction, font embedding)
- **Editorial design** (magazine/newspaper layout, book typesetting)
- **Text rendering** (canvas, SVG, font metrics)
- **Documentation, translations, and testing**
To ask a question, share what you're building or just say hello, join the [Postext Discord](https://discord.gg/CSzm6hr8YD). New versions, videos and closed issues are announced there too.
For the full community vision and all the ways to get involved, see the [Contributing guide](https://postext.dev/en/docs/contributing).
---
## Acknowledgments
**[pretext](https://github.com/chenglou/pretext)** by Cheng Lou. The foundational text measurement library that makes postext possible. Without DOM-free, pixel-perfect text measurement at sub-millisecond speed, none of this would be practical.
**Content First** (~2014). The original exploration into high-quality editorial layout on the web. A decade of running into walls, learning what doesn't work, and accumulating the conviction that this problem is worth solving properly.
postext stands on centuries of typographic tradition. The rules it implements are not invented — they are inherited from the work of typesetters, typographers, and designers who refined the art of making text readable long before screens existed. From Gutenberg's movable type to Tschichold's asymmetric typography to Bringhurst's *Elements of Typographic Style* — postext aims to bring that accumulated craft to the web, where it has been conspicuously absent.
---
## License
MIT
