Configuration

Postext Configuration

What a Postext configuration is, and where each group of settings is explained in the nineteen pages of the reference

Generated from docs/configuration-en.mdx (updated 2026-10-19). 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

This page opens the reference for every setting that controls how your pages look. One group of settings holds all the choices: page size, number of columns, fonts, text size, headings, boxes, colours and more. You only write the settings you want to change, because each one starts with a sensible value. The reference is split into nineteen pages. The list on this page links every section, so jump to the part you need.

Every layout decision in Postext is driven by a single configuration object.

PostextConfig controls page dimensions, column layout, body text typography, heading styles, the document language (locale), and more. Every property is optional — Postext ships with sensible defaults inspired by traditional book typography. You only need to specify what you want to change.

import { buildDocument } from 'postext';

const document = buildDocument(content, {
  page: { sizePreset: '21x28', dpi: 300 },
  layout: { layoutType: 'double', gutterWidth: { value: 0.5, unit: 'cm' } },
  bodyText: { fontFamily: 'EB Garamond', fontSize: { value: 9, unit: 'pt' } }, // 9 pt overrides the 8 pt default
  headings: { fontFamily: 'Open Sans' },
});

For an overview of how the engine processes this configuration, see the Architecture page.

Index

The reference is split into nineteen pages. Each group below is one page, followed by the sections it holds.

Page and layout

• Page — size, margins, baseline grid, cut lines, numbering, binding.
• Layout — column count, gutters, rules, vertical writing.

Headers and footers

• Headers & footers — the text, rule, box and image elements of every page, with placeholders, parity, page roles and placement.

Body text

• Body text — typography, justification and line breaking, blockquotes, verse, tab stops and drop caps.

Hyphenation and language

• Hyphenation — hyphenation patterns, words kept whole, ragged text.
• Document language — the top-level locale, which sets the hyphenation fallback, the built-in resource types, the continuation strings of tables and split callouts, and the language tagged in an accessible PDF; the digits (numerals) and the text direction (direction) it implies; and the languages and scripts Postext sets. The guide to right-to-left books is Arabic layout.
• Languages and scripts — the writing systems Postext sets, and the pages that explain each.
• Arabic text — shaping, kashida, vowel marks and digits of Arabic text.

Headings

• Headings — shared defaults and H1–H6 overrides.

Widows, orphans and balancing

• Orphans, widows, runts, and keep-together rules — bodyText keys that keep lines and blocks together across a column break.
• Column balancing — the levers that make every column end level, in editorial order.

Lists and maths

• Unordered lists and Ordered lists — bullets, numbering, nesting.
• Math — LaTeX rendering, scale, colour, margins.

Notes and references

• Footnotes — footnotes: where the notes cited with [^id] go, how they are numbered and how they look.
• Line numbers — lineNumbers: a number in the margin on every fifth line of verse, or of the text: what is counted, where the count starts again, and which side the numbers go on.
• Cross-references — crossRefs: the words printed around the number or the page of a :ref, and its default style.
• Citations — citations: the citation style, and the look of citations and of the bibliography.
• Table of contents — what :::toc prints: entry typography, leaders, page numbers, author lines, part rows.
• Back-of-book index — what :::index prints: entry typography, indents, page-number separators and ranges, letter groups, sorting language.

East Asian typography

• East Asian typography — cjk: the regional conventions and line breaking of Chinese, Japanese and Korean text, how their justified lines are spread, punctuation widths and hanging, the space between Han and Latin, the character grid, upright numbers in vertical text, and the marks, ruby, warichu notes and kanbun marks. The guides to all of it are Chinese layout and Japanese layout.

Resources and tables

• Resource types — typed numbering for figures, tables, and custom kinds.
• Table style (with named table styles) and Caption style — typography and decoration for table resources and their captions.
• Diagram style — recolouring embedded SVG diagrams in a single ink for spot-colour printing.
• Score style — scoreStyle and scoreStyles: staff size, music font, spacing and bar numbers of every music score.
• Video style — videoStyle: the play mark and the QR code printed over a video's poster, and what its players offer in the HTML viewer and in EPUB.

Styles and parts

• Paragraph styles — named styles for :::paragraphs containers: bibliographies, glossaries, notes.
• Chip styles — chipStyles: named styles for the inline :chip[…]: the box of a word bank, a keyboard key, a tag.
• Highlight styles — markStyles: named styles for the inline :mark[…]: the band behind a highlighted phrase that breaks across lines.
• Code listings — codeStyle: the face, box, tab width, long lines, line numbers and token colours of ``` listings, the syntax colouring and its highlighter hook, and inline code in a code face.
• Parts — part-divider pages for :::part containers: parity, body area, opener design, body typography.
• Heading styles — named styles for {style="…"} headings: unnumbered chapters, front matter with its own running heads, geometry and palette.

Callout boxes

• Callout styles — boxed notes, tips and objectives for :::callout containers.

Comics settings

• Comics — comics: the frame and gutters of comic pages, panel styles, lettering, balloon styles and the cast. The guide is Comics.

Composed pages settings

• Page templates — pageTemplates: the frames, groups and decoration of a composed page, inheritance between templates and recto/verso variants. Label styles — labelStyles: the look of the labels set at a picture's anchors. Frame looks — frameLooks: named colours a piece of a composed page wears with look="…". Every problem a template can have is listed in Page template warnings.

Fonts, colours and output

• Units and colors + Color palette — Dimension, ColorValue, named colors.
• Custom fonts — declare user-uploaded font families alongside Google Fonts.
• HTML viewer — target column width and line-breaking for the HTML backend.
• Canvas viewer — canvasViewer: the space between the two pages of a pair and between one row and the next in the Sandbox's Canvas.
• PDF generation (config) — outlines, accessible (tagged) output, forced colour space for the PDF backend.
• Print production (config) — print: PDF/X-1a and PDF/X-4, the ICC output profiles, black (K-only greys, overprint, rich black), colours authored in CMYK, the preflight and the print preview.
• Contrast check (config) — contrast: text against its ground at WCAG AA or AAA, on screen and on the paper of the output profile, and reversed text too fine for the press.
• Content check (config) — checks.contentInConfig: flags texts in the design that hold the book's own text instead of placeholders, with an allow list for the title and the publisher.
• Folio viewer (config) — paper stock, binding, surface and light of the 3D book viewer.
• Debug — visual overlays and authoring warnings for the editor.

Programmatic usage

• Programmatic use — buildDocument, the warnings it reports, resolvers, caches.
• Running layout in a Web Worker — off-main-thread builds with cancellation.

PDF files

• Generating PDFs — postext-pdf: font providers, CJK fonts, workers and print-ready files.

HTML, Folio and EPUB

• Integrating the HTML viewer and Generating PDFs — end-to-end recipes.
• A 3D book (postext-folio) — the laid-out document as a printed book lying open on a desk, with leaves the reader turns.
• EPUB books — fixed-layout and reflowable EPUB 3 files from the same layout, and checking them with EPUBCheck.

.postext bundles

• Bundles (.postext files) — a whole book in one file: creating, opening and building .postext archives from code.

---

Configuration: page, numbering and layout →