Postext Configuration

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

This reference is long. These are the main blocks:

• Page — size, margins, baseline grid, cut lines.
• Layout — column count, gutters, rules.
• Headers & footers — per-page text and rule elements with placeholders, parity, and alignment.
• Body text — typography, hyphenation, orphans and widows.
• Document language — the top-level locale: hyphenation fallback, table continuation strings, the language tagged into an accessible PDF.
• Headings — shared defaults and H1–H6 overrides.
• Unordered lists and Ordered lists — bullets, numbering, nesting.
• Math — LaTeX rendering, scale, colour, margins.
• 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 — single-ink recolouring of embedded SVG diagrams for spot-colour printing.
• Paragraph styles — named styles for :::paragraphs containers: bibliographies, glossaries, notes.
• Callout styles — boxed notes, tips and objectives for :::callout containers.
• 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.
• Table of contents — what :::toc prints: entry typography, leaders, page numbers, author lines, part rows.
• 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.
• PDF generation (config) — outlines, accessible (tagged) output, forced colour space for the PDF backend.
• Debug — visual overlays and authoring warnings for the editor.
• Programmatic use — buildDocument, resolvers, caches.
• Running layout in a Web Worker — off-main-thread builds with cancellation.
• Integrating the HTML viewer and Generating PDFs — end-to-end recipes.

#Page

The page property controls the physical dimensions and appearance of the page.

#Mirrored margins

Books are read as spreads, and the inner margin usually differs from the outer one. margins.mirror turns the four margins into facing-page margins:

{
  "page": {
    "margins": {
      "top": { "value": 2, "unit": "cm" },
      "bottom": { "value": 2.5, "unit": "cm" },
      "left": { "value": 2.2, "unit": "cm" },
      "right": { "value": 1.4, "unit": "cm" },
      "mirror": true
    }
  }
}

With this configuration every odd page has a 2.2 cm margin on the left (the spine) and 1.4 cm on the right (the fore-edge); every even page has 1.4 cm on the left (the fore-edge) and 2.2 cm on the right (the spine). Each laid-out page carries its own contentArea on the VDTPage, so everything derived from it — columns, full-width float bands, header and footer containers, and span: 'page' opener bands — follows the mirrored geometry automatically. Page and bleed frames used by design elements anchored to 'page' / 'bleed' are not affected: they describe the physical sheet, not the margins.

#Page size presets

#Baseline grid

The baseline grid draws horizontal lines at intervals matching the body text line height. It is a visual aid for ensuring vertical rhythm — when enabled, the engine snaps heading blocks to the grid so that body text in adjacent columns stays aligned. The lines span only the page's actual text — from the first text line to the last — so float bands, blank parity pages, and unused tail space show no grid.

page: {
  baselineGrid: { enabled: true, color: { hex: '#e0e0e0', model: 'hex' } }
}

#Cut lines

When enabled, the canvas expands to include a bleed area and the engine draws crop marks at each corner for print production.

#Numbering

The page.pageNumbering block controls how page labels are formatted and where the counter starts. It only defines the document-wide default — to restart numbering mid-document (e.g. roman-numeral front matter switching to decimal chapters from 1), use the :::numbering directive (see Document format → Directives).

The computed label is stored on every VDTPage as pageLabel and is what the {pageNumber} header/footer placeholder resolves to. PDFs emit a /PageLabels number tree so Preview / Acrobat's page indicator and "Go to page" navigation match the printed labels exactly.

#Layout

The layout property controls how columns are arranged within the content area.

#Column rule

Draws a thin vertical line in the gutter to visually separate columns.

#Layout types

• 'single' — One column spanning the full content width. Best for narrow pages or text-heavy content with long paragraphs.

• 'double' — Two equal-width columns. The classic editorial layout — keeps line measure within the optimal 40–50 character range for comfortable reading.

• 'oneAndHalf' — An asymmetric layout with a main column and a narrower side column. The side column (controlled by sideColumnPercent) is ideal for margin notes, small figures, or supporting content. Values between 25–40% work well. With sideColumnRole: 'floats' the body text never enters the side column: it becomes a channel for the figures, tables and callouts placed with span: 'side'. A side figure or table stacks from the head of the channel on the page that first cites it — the marginal figure of a textbook sits at the top of its page even when the text cites it further down; one that cannot fit the rest of the channel waits for the next page's. A side box stacks beside the text it interrupts, and when the rest of the channel cannot hold it there it slides up to the lowest position that still fits (its foot on the channel's foot), or waits for the next page. span: 'page' floats and boxes still cross both columns, and a column float with placement.captionSide puts its caption in the channel, level with the figure. Combined with mirrored margins and sideColumnSide: 'outer', the channel sits at the outer edge of every page — the marginal column of a textbook.

#Headers & footers

The header and footer properties control per-page header and footer slots. Headers and footers render inside the existing page margins — they do not reserve additional space and do not shrink the content area.

Container frame. An element anchored to 'container' is placed in the margin band between the body and the trim edge, spanning the content-area width. The header container runs from the trim top down to the top of the body; the footer container from the bottom of the body down to the trim bottom. So top-* header anchors and bottom-* footer anchors measure from the trim edge, while bottom-* header anchors and top-* footer anchors measure from the body edge. The container never includes the bleed or the crop-marks band, so a header or footer lands at the same position on the trimmed page whether page.cutLines is on or off. Anchor to 'page' (the trim box) or 'bleed' to reach beyond the content-area width or into the bleed.

Slots use the unified design slot model: every element has a placement with an anchor (to the container or to another element by #id), an optional offset, and an optional size. The legacy flat fields align, marginFromBody, marginFromEdge, and width: 'full' are still accepted on input and are migrated to the new shape automatically; the equivalent new-shape description is documented below.

Each slot holds a list of text, rule, and box elements. Array order is paint order (first element paints first, last element paints on top). This holds whatever the anchors say: an element may anchor to one listed after it (anchor.to: '#ttl'), so a background box can come first and still be positioned against the text it sits behind.

Built-in defaults. When header or footer is undefined, postext applies a sensible built-in default rather than an empty slot:

• Default header: {title} right-aligned on odd pages, {chapterTitle} left-aligned on even pages, and a full-width rule — all in the palette's main color, Open Sans 8pt/600, marginFromBody 16pt (text) / 13pt (rule).
• Default footer: {pageNumber} centered on every page in the palette's main color, Open Sans 8pt/600, marginFromBody 16pt.

To opt out of the built-in defaults, set header: { elements: [] } (or footer: { elements: [] }). An explicit empty elements array is preserved as "no elements" — only undefined triggers the defaults.

#Text elements

Text elements render a template string with placeholder substitution. Placeholders use {name} syntax; {{ and }} emit literal braces.

The defaults in the table below are those of a text element you add yourself. The built-in header and footer described under Built-in defaults above are ready-made elements with their own values (Open Sans 8pt/600 in the palette's main colour), not the element defaults.

Available placeholders:

• {pageNumber} — 1-based page number of the current page.
• {totalPages} — total page count for the document.
• {title}, {subtitle}, {author}, {publishDate} — values read from content.metadata. Unknown or empty metadata renders as an empty string (and raises a warning in the sandbox).
• {chapterTitle} — text of the most recent H1 on or before the current page.
• {partTitle}, {partNumber} — title and number of the current part (the most recent :::part page on or before the current page; blank parity pages just before a part page already belong to it). Empty before the first part.

Edge-implied alignment

When a text element's placement.anchor.to references another element by #id, the anchor edge implies a default text alignment for wrapped lines:

• right-of and align-left imply text align: 'left' — wrapped lines flow rightward from the anchor.
• left-of and align-right imply align: 'right' — wrapped lines hug the side closest to the anchor target.

The sandbox heading editor applies these implied alignments automatically when you change the anchor edge or target. They keep multi-line wrapped text visually anchored to the element it relates to (so e.g. the "P" of a wrapped "Postext" lines up vertically under the "I" of "Introduction").

#Rule elements

Rule elements render a line: horizontal across the slot, or vertical down it.

#Box elements

Box elements paint a rounded rectangle inside the slot — useful as a backdrop behind text in chapter openers, sidebars or footers. Box elements are positioned exclusively through the placement field; they have no legacy flat shorthand. Fill, stroke and corner radius live in the nested style object (ElementBoxStyle), as in the JSON example under "Element placement".

#Image elements

An image element draws a bitmap or SVG resource of the document — a publisher's logo on a title page, a mark in a running head. It is sized by its placement.size: with one of width / height left 'auto' (the default) the other side follows the image's aspect ratio; with both set the image is fitted inside the box and centred. A missing or non-image resource draws nothing.

{
  kind: 'image', id: 'logo', resourceId: 'logo-publisher',
  placement: { anchor: { to: 'page', edge: 'top-left' }, offset: { x: { value: 64, unit: 'mm' }, y: { value: 233, unit: 'mm' } }, size: { width: { value: 83, unit: 'mm' }, height: 'auto' } },
}

The PDF backend embeds the resource like a figure (an SVG with a print master uses it); the HTML viewer resolves it through resourceImageUrl.

#Element placement

ElementPlacement is the unified positioning model used by every element type (text, rule, box) inside any design slot — page header, page footer, or heading-level advanced design slot. Three pieces of state describe a placement:

interface ElementPlacement {
  /** What this element anchors to and which edge of that target. */
  anchor: {
    to: 'container' | 'page' | 'bleed' | `#${string}`; // container = the slot; page = trim box; bleed = trim box + bleed; #id = another element
    edge: AnchorEdge;
  };
  /** Distance from the anchor point. */
  offset?: { x?: Dimension; y?: Dimension };
  /** Optional fixed width / height. Width also accepts 'fill' (span the slot).
   *  `maxWidth` caps an 'auto' width (text): the element still shrink-wraps its
   *  content, so elements anchored to it stay attached, but a long text wraps or
   *  ellipsizes there — a running head can reserve room for the label hanging
   *  off it instead of squeezing that label out. */
  size?: { width?: Dimension | 'fill' | 'auto'; height?: Dimension | 'fill' | 'auto'; maxWidth?: Dimension };
}

AnchorEdge accepts:

• Container edges (when anchor.to is 'container', 'page' or 'bleed'): top, top-left, top-right, bottom, bottom-left, bottom-right, left, right.
• Element-relative edges (when anchor.to === '#someId'): right-of, left-of, below, above, align-top, align-bottom, align-left, align-right.

anchor.to: 'page' anchors the element to the trim box (the physical page after cutting) and 'bleed' to the trim box grown by cutLines.bleed on every side (identical to the trim box while cut lines are disabled). Both frames also become the reference for size: 'fill' and for the automatic width clamp, so a coloured band can run edge to edge regardless of the page margins:

{ "kind": "box", "id": "band", "placement": { "anchor": { "to": "bleed", "edge": "top-left" }, "size": { "width": "fill", "height": { "value": 6, "unit": "cm" } } }, "style": { "backgroundColor": { "hex": "#1d3557", "model": "hex" } } }

Inside a heading's advanced-design slot, page- and bleed-anchored elements do not grow the height reserved for the heading unless they extend below the heading's top edge (a band across the top of the page sits behind the opener; a band reaching below the heading pushes the body text down). Use advancedDesign.minHeight to reserve a fixed opener height regardless.

Each element has a stable id (auto-assigned by the sandbox; you can also set it by hand). Elements anchored to other elements form a small dependency graph that the engine resolves before measuring, so an element can chain off another without manual coordinates.

The legacy align + marginFromBody + marginFromEdge shape is parsed on input and rewritten into a placement at config-resolution time, so existing configs keep working unchanged.

#Body text

The bodyText property controls the typography of all paragraph text.

#Hyphenation

When text alignment is set to 'justify', hyphenation prevents excessive word spacing by breaking long words at syllable boundaries. The engine uses TeX/Liang patterns to find natural break points at syllable boundaries. See Hyphenation & Justification for a detailed explanation.

Supported locales: 'en-us' (English), 'es' (Spanish), 'fr' (French), 'de' (German), 'it' (Italian), 'pt' (Portuguese), 'ca' (Catalan), 'nl' (Dutch).

Words shorter than 5 characters are never hyphenated. The engine requires at least 2 characters before and 3 characters after a break point.

Document language

The top-level locale is the language of the document as a whole. It takes the same values as hyphenation.locale and is the fallback when that field is unset, so a Spanish book only needs locale: 'es' to hyphenate in Spanish. It also picks the language of the built-in table continuation strings ((cont.) / Continued versus Continúa, see Tables taller than the page) and is the language tagged into an accessible PDF. Unset, the engine assumes 'en-us'; the sandbox falls back to the interface language and exposes the field at the top of the Body text section.

const config: PostextConfig = {
  locale: 'es',
  bodyText: { textAlign: 'justify', hyphenation: { enabled: true } }, // hyphenates in Spanish
};

#Orphans, widows, runts, and keep-together rules

See Hyphenation & Justification for the mechanics behind these demerits. This section is the reference for the bodyText keys that drive them.

Beyond hyphenation and spacing bounds, the body-text configuration exposes the soft rules that prevent structurally awkward paragraph breaks. All of these are fed into the Knuth-Plass line-breaking algorithm as demerits — they bias the layout toward clean breaks without ever forcing a hard rule. Set the *Penalty values to 0 to effectively disable any one of them.

About runts. A runt is a paragraph whose last line is too short to feel like a proper line of text — typically one or two short words marooned at the end of a paragraph. Because the check is based on the pixel length of the line relative to the normal space width, runtMinCharacters adapts automatically to the current font size. A short word that is visually wider than runtMinCharacters × spaceWidth is fine; a word that is narrower than that (or truly alone) attracts the runt penalty. For the mathematically curious: at the default runtPenalty of 1000, avoiding a runt dominates any alternative break set requiring up to roughly r≈2.15 word-spacing stretch.

Soft, not hard. None of these rules can prevent a break — the engine will always produce a layout. They are demerits: the algorithm trades off badness, hyphenation cost, fitness-class smoothness, and these structural penalties in a single global optimisation and picks the break set with the lowest total cost. If you need a harder guarantee, raise the penalty; if a given document reads better with the penalty relaxed, lower it.

#Headings

The headings property controls typography for all heading levels (H1–H6). You can set general defaults that apply to all levels, then override specific properties per level.

#General defaults

#Column balancing

Publishers expect every column to start at the top of the page and end flush with its bottom. Break rules (orphan/widow protection, headings kept with their text, unsplittable figures) naturally leave short columns — one or more empty baseline-grid lines at the bottom. When balancing is enabled, the engine does what a compositor would, applying three levers in editorial priority order:

0. A box closing the column — a callout that ends a short column is pushed down by the exact room under its foot, so its bottom edge lands on the last grid slot of the page, level with the last line of the column beside it.
1. Headings — whole grid lines are added to the top margin of the headings inside the short column. When several lines are needed and the column holds several headings, the lines are distributed among them, always giving the largest share to the most important heading (an h2 receives more than an h3). Headings sitting at the very top of a column never receive extra space, so columns keep starting at the page top.
2. List ends — when the headings cannot absorb the whole gap, a grid line is added where a list/enumeration ends (space after a list reads naturally), capped per list end.
3. Loose paragraphs — as a last resort, one paragraph of the column is re-broken one line longer (TeX's \looseness=+1), choosing the longest paragraph so the extra word spacing dilutes invisibly. The loose solution is only accepted when every line stays below bodyText.maxWordSpacing — type colour never exceeds the limit you already configured. Requires bodyText.optimalLineBreaking.

The last column of a page is only balanced when the page flows naturally into the next one — a chapter's closing page legitimately ends short.

#Per-level overrides

Each heading level can override the general defaults via the levels array. Only fontSize (plus H1's breakBefore, noted below) differs by default — all other properties inherit from the general heading settings.

The H1 default models a book-style chapter layout: every top-level heading opens on a fresh right-hand (odd) page, with a mandatory blank separator page from the previous chapter. Override it on levels[0].breakBefore if your document is flatter than a book.

Per-level overrides support the same properties as the general defaults — fontSize, lineHeight, fontFamily, color, fontWeight, marginTop, marginBottom — plus two level-only fields:

headings: {
  fontFamily: 'Merriweather',
  levels: [
    // Canonical book preset: chapters on a right-hand (odd) page.
    { level: 1, fontSize: { value: 24, unit: 'pt' }, breakBefore: { enabled: true, parity: 'odd' } },
    { level: 2, fontSize: { value: 18, unit: 'pt' }, italic: true },
  ]
}

#Break before

breakBefore is orthogonal to the numbering controls: turning it on forces a page break, but the numeric counter only resets when you explicitly insert a :::numbering directive. Blank parity pages count as real pages in the sequence and receive headers/footers according to their normal odd/even rules.

Parity values

Blank-page ownership

Blank pages inserted by breakBefore carry chapter-title headers based on why they were inserted:

• Pages inserted to satisfy a parity constraint ('odd', 'even', or the parity tail of 'always-*') belong to the upcoming chapter. Their {chapterTitle} header placeholder resolves to the new chapter's title — because the blank exists only to push the new chapter onto the correct parity.
• The mandatory leading separator inserted by 'always-odd' / 'always-even' belongs to the previous chapter. It's a deliberate end-of-chapter breath, so the {chapterTitle} header still shows the old chapter's title.

Document-start exception

When the very first block of the document is a heading with breakBefore enabled — or the source opens with :::pagebreak — parity enforcement is skipped while the first page is still empty. The heading lands on page 1 as written, regardless of the configured parity, so a document that begins with a # Chapter 1 configured parity: 'odd' doesn't inherit a spurious leading blank. Once any content has been placed, parity enforcement behaves normally.

#Span and advanced design

Each heading level accepts two additional fields that control how the heading renders as a full page-wide chapter opener.

Example — a minimalist chapter opener that shows "Chapter N" above the title:

{
  "headings": {
    "levels": [
      {
        "level": 1,
        "span": "page",
        "breakBefore": { "enabled": true, "parity": "always-odd" },
        "advancedDesign": {
          "enabled": true,
          "slot": {
            "elements": [
              {
                "kind": "text",
                "id": "chapterLabel",
                "placement": {
                  "anchor": { "to": "container", "edge": "top" },
                  "offset": { "y": { "value": 48, "unit": "pt" } },
                  "size": { "width": "fill" }
                },
                "content": "Chapter {numberRoman}",
                "fontSize": { "value": 10, "unit": "pt" },
                "align": "center",
                "overflow": "ellipsis-end"
              },
              {
                "kind": "text",
                "id": "chapterTitle",
                "placement": {
                  "anchor": { "to": "#chapterLabel", "edge": "below" },
                  "offset": { "y": { "value": 12, "unit": "pt" } },
                  "size": { "width": "fill" }
                },
                "content": "{titleText}",
                "fontSize": { "value": 24, "unit": "pt" },
                "fontWeight": 700,
                "align": "center",
                "overflow": "wrap",
                "hyphenate": true
              }
            ]
          }
        }
      }
    ]
  }
}

Heading placeholders available inside a level's design slot:

• {titleText} — the heading's plain text (without numbering prefix).
• {number} — the formatted number per the level's numberingTemplate.
• {numberDecimal}, {numberRoman}, {numberRomanLower}, {numberAlpha}, {numberAlphaLower} — alternative numeral formats.
• {chapterNumber}, {chapterTitle}, {pageNumber}, {totalPages}, {title}, {subtitle}, {author}, {publishDate} — shared metadata placeholders.
• {attr.<key>} — an attribute written on the heading line itself (# Title {author="I. Zango Martín"}), falling back to the current chapter's H1 attribute. Missing attributes resolve to an empty string with no warning.

#Unordered Lists

The unorderedLists property controls how bullet lists (-, *, +) and GFM task lists (- [ ], - [x]) are rendered. Up to five levels of nesting are supported.

#Unordered list defaults

#Task list extensions

GFM task items (- [ ] …, - [x] …) are rendered as unordered items with a checkbox glyph replacing the bullet. The following fields only apply to task items:

#Unordered per-level overrides

Each entry in levels targets one depth (1–5) and can override any of the following:

Indent cascade. Level 1 always starts at the general indent value (by default 0 em — bullets are pinned to the column edge). For levels 2–5, if you leave indent undefined the engine places the bullet at the previous level's text-start (parent indent + bullet width + gap). Set an explicit indent on a level to break the cascade and pin that depth anywhere you like.

unorderedLists: {
  bulletChar: '—',
  gap: { value: 0.4, unit: 'em' },
  hangingIndent: true,
  levels: [
    { level: 2, bulletChar: '·' },
    { level: 3, bulletChar: '◦', color: { hex: '#666666', model: 'hex' } },
  ],
}

#Ordered Lists

The orderedLists property controls numbered lists (1., 2), etc.). Up to five levels of nesting are supported and each depth can use a different number format.

#Ordered list defaults

#Ordered per-level overrides

Each entry in levels can override numberFormat, separator, fontFamily, fontSize, color, fontWeight, italic, indent, verticalOffset and the separator style (separatorFontFamily, separatorFontWeight, separatorItalic, separatorColor, separatorGap) — the same indent cascade as unordered lists applies. A level's separator style inherits its own number style unless the list-wide separator setting is given.

Right alignment. The pipeline measures the widest formatted number within a run and indents all items in that run so the number markers line up on their right edge. A list of ten items rendered as 1. – 10. has the single-digit numbers right-padded so the separator stays in the same column.

orderedLists: {
  numberFormat: 'arabic',
  separator: '.',
  levels: [
    { level: 2, numberFormat: 'lower-alpha' },
    { level: 3, numberFormat: 'lower-roman', separator: ')' },
  ],
}

This yields the classic nested mix:

1. First item
   a. Sub-item
      i) Deep note
   b. Sub-item
2. Second item

#Math

The math property controls how LaTeX formulas inside $...$ (inline) and $$...$$ (display) delimiters are parsed and rendered. The underlying engine is MathJax (the mathjax-full package) in SVG output mode, rasterised to the canvas and embedded as scalable glyphs in the PDF.

interface MathConfig {
  enabled?: boolean;        // Render LaTeX. When false, spans pass through as literal TeX.
  fontSizeScale?: number;   // Multiplier applied to the body font size.
  color?: ColorValue;       // Formula colour; inherits body colour if omitted.
  marginTop?: Dimension;    // Space above display math blocks.
  marginBottom?: Dimension; // Minimum space below; baseline grid snap may enlarge it.
}

math: {
  enabled: true,
  fontSizeScale: 1.0,
  color: { hex: '#295AA3', model: 'hex' },
  marginTop: { value: 1, unit: 'em' },
  marginBottom: { value: 1, unit: 'em' },
}

Resolver and stripper match the other sections:

import {
  DEFAULT_MATH_CONFIG,
  resolveMathConfig,
  stripMathDefaults,
} from 'postext';
 
const resolved = resolveMathConfig(config.math);
const minimal  = stripMathDefaults(config.math);

For the document-side grammar ($...$, $$...$$, escaping a literal dollar), see Document format.

#Resource types

A resource type is a user-definable category — Figure, Table, Diagram, Listing… — that drives how the resources of that kind are numbered, captioned, and referenced. The list lives on config.resourceTypes; the sandbox edits it through a dedicated section of the configuration panel.

When config.resourceTypes is unset, Postext ships two built-in defaults: Figure and Table, both numbered {h1}.{n} (resetting on every level-1 heading) with decimal counters.

The built-in defaults are locale-aware. The exported defaultResourceTypes(locale = 'en') localizes the type names, short labels, and caption prefixes to the document's locale — English yields Figure/Fig. and Table/Tab.; Spanish yields Figura/Fig. and Tabla/Tabla. Regional tags such as es-ES resolve by language, and any locale without translations falls back to English. The numbering behaviour (numberingTemplate: '{h1}.{n}', resetOn: 'h1', decimal counters) is language-independent. Each call returns fresh objects, so you can mutate the result freely:

import { defaultResourceTypes } from 'postext';
 
const types = defaultResourceTypes('es');
// => [{ id: 'figure', name: 'Figura', shortLabel: 'Fig.', captionPrefix: 'Figura',
//       numberingTemplate: '{h1}.{n}', resetOn: 'h1', counterFormat: 'decimal', … },
//     { id: 'table',  name: 'Tabla',  shortLabel: 'Tabla', captionPrefix: 'Tabla', … }]

type ResourceCounterFormat =
  | 'decimal'
  | 'roman-lower'
  | 'roman-upper'
  | 'alpha-lower'
  | 'alpha-upper';
 
type ResourceCounterReset = 'never' | 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6';
 
interface ResourcePlacement {
  position?: 'auto' | 'top' | 'bottom' | 'here'; // which free slot a float may take; 'here' = inline embed at the ::resource directive
  span?: 'column' | 'page' | 'side';             // one column, the full content width, or the float-only side column
  rotate?: 'ccw' | 'cw';                         // a quarter turn: a landscape table on a page of its own
  width?: number;                                // fraction (0 < width < 1) of the column or page width; default: the whole width
  align?: 'left' | 'center' | 'right';           // where a float narrower than its column sits; default 'left'
  captionSide?: boolean;                         // caption beside the figure, in the side column of a oneAndHalf layout (column floats only)
}
 
interface ResourceType {
  id: string;                          // stable id, referenced by Resource.typeId
  name: string;                        // singular display name, e.g. "Figure"
  namePlural?: string;                 // optional plural, e.g. "Figures"
  shortLabel: string;                  // compact label for inline refs, e.g. "Fig."
  numberingTemplate: string;           // "{h1}.{n}" or "{n}"
  resetOn: ResourceCounterReset;       // when the {n} counter resets
  counterFormat: ResourceCounterFormat;// how {n} is formatted
  captionPrefix: string;               // prepended to the caption, e.g. "Figure"
  defaultPlacement?: ResourcePlacement;// fallback placement for this type's resources
}

ResourcePlacement is the same shape a resource sets on its own placement. position picks the kind of free slot a float may take — auto (the default) takes the first one after the first reference, top / bottom restrict it to that kind of band, here embeds the resource inline. span sets the float's extent: one column, the full content width, or the float-only side column of a column-and-a-half layout. rotate turns the resource a quarter turn and makes it a page-span float on a page of its own. width narrows a float to a fraction of its column (or of the page for a page-span float) — a small table in a wide column, say. align says where such a narrower float sits — left by default, centre or right. captionSide sets the caption beside the figure in the float-only side column of a column-and-a-half layout (layout.sideColumnRole: 'floats'), level with the figure's top (its bottom for a bottom float); it applies to column floats only, and a page without such a column keeps the caption under the figure. When neither the resource nor its type sets a placement, the built-in default is auto / column.

#Template tokens

numberingTemplate is rendered with the same engine as heading numbering (see Headings). It recognises two kinds of token:

• {n} — the per-type counter, formatted per counterFormat. This is the value that increments per resource and resets according to resetOn.
• {h1} … {h6} — the heading numbers in effect at the point of first reference, always rendered as decimals. {h1} is the current level-1 heading number, {h2} the level-2, and so on.

Any other text is literal. A backslash escapes a literal {, }, or \. When a heading token has no value in scope (e.g. {h1} before any level-1 heading), it collapses together with its adjacent separator — so {h1}.{n} degrades gracefully to the bare counter.

#Numbering and references

The number a resource type produces is what :ref prints and what the caption prefix precedes. :ref{id} is the primary form: the first reference in reading order incorporates the resource, which floats to the first free slot after that reference — the bottom of the referencing column, the top or bottom of the next empty column, or a band of the next page (per its resolved placement — position: 'auto' | 'top' | 'bottom' | 'here' and span: 'column' | 'page' | 'side', plus rotate, width, align and captionSide, resolved per resource, then the type's defaultPlacement, then the built-in auto / column; 'top' / 'bottom' restrict the search to that kind of slot). The ::resource{id} block embed is optional and only needed for placement.position: 'here' — an inline, non-floating embed at an exact point in the flow. The full document-side grammar — both forms plus :ref's style and text options — is documented in Document format › Resources, including how first-reference order drives the count.

This mirrors heading numbering: just as a heading level carries a numberingTemplate, a resource type carries one too — but the resource counter ({n}) advances per first-reference rather than per heading, and resetOn ties it back to the heading hierarchy.

#Table style

The tableStyle property controls the typography and decoration of table resources — every table's, unless it picks a named table style. Body and header cells are styled independently. Font family, size, and colours inherit the resolved body text when unset, so a document with no tableStyle renders tables with body-text typography.

const config: PostextConfig = {
  tableStyle: {
    headerBold: true,
    headerBackground: { hex: '#f0f0f0', model: 'hex' },
    borders: true,
    borderWidth: { value: 0.75, unit: 'pt' },
  },
};

Border widths are kept fractional: a 0.5pt rule is stroked as a hairline in the PDF and on screen rather than being rounded up to a full pixel (the floor is 0.25px).

#Named table styles

A document rarely sets every table alike: a checklist in a navy grid with a rounded frame, an option row boxed by its outer frame only, a data table in plain horizontal rules. tableStyles declares named variants, and a table resource picks one with table.styleId. Every field a style leaves unset is read from tableStyle first and from the body text after that, so a style states only what sets its tables apart. A table without a styleId, or with an id no style declares, keeps tableStyle — a document without tableStyles renders exactly as before.

const config: PostextConfig = {
  tableStyle: {
    borderColor: { hex: '#163a76', model: 'hex' },
    borderWidth: { value: 1.3, unit: 'pt' },
    borderRadius: { value: 10, unit: 'pt' },
  },
  tableStyles: [
    {
      id: 'option',
      name: 'Option row',
      rules: 'outer',
      borderColor: { hex: '#7a9cc6', model: 'hex' },
      borderWidth: { value: 1, unit: 'pt' },
      borderRadius: { value: 8, unit: 'pt' },
      headerBackgroundEnabled: false,
    },
  ],
};
 
// In the resources: this table is set in the "option" style.
const resource: Resource = {
  id: 'choices', typeId: 'table', kind: 'table', createdAt: 0, updatedAt: 0,
  table: { model: { rows: [/* … */] }, styleId: 'option' },
};

Each entry takes every tableStyle field plus id (what table.styleId references) and an optional name for the editor (defaults to the id). Everything a style can set applies per table — typography, fills, borders, rules, corner radius, padding and the overflow behaviour with its continuation strings. resolveTableStylesConfig(styles, tableStyle, resolvedBodyText, locale?) returns the resolved list, pickTableStyle(resolved, styleId) the style a table is set in, and stripTableStylesDefaults drops the unset fields (it keeps a field equal to its built-in default, which still overrides a different tableStyle value).

#Tables taller than the page

A floated table that does not fit the fresh page it is offered is not squeezed or overflowed: with overflow: 'split' (the default) the engine cuts it between rows at the last edge that fits the page and continues it on the following pages, as many as it takes. Every continued part repeats the table's header rows (TableModel.headerRowCount, or the leading rows made of header cells when it is unset) and carries the caption again with continuedSuffix after the description — "Table 6-4. Title (cont.)". Every part that goes on gets continuesMarker under it, flush right, in the note typeface; the table's note is held back for the last part. A cut never runs through a merged cell (a rowspan moves whole to the next part), and a row that heads the rows below it — a single cell across the whole table — is carried to the next part rather than left stranded at the foot of a page.

'clip' keeps the leading rows that fit the page and drops the rest silently (the note still closes the part); 'hide' leaves the table out altogether. Both apply only when the table is taller than a page: a table that fits is placed whole in any mode. Inline (placement.position: 'here') tables are not split.

The continuation strings default per document language (locale, else the hyphenation locale): English (cont.) / Continued, Spanish (cont.) / Continúa.

Cell content is inline markdown, and a line break inside a cell starts a new paragraph. A paragraph that opens with a bullet or dash (•, -, *, –) or a number (1., 1)) followed by a space is set as a list item: the marker is painted as written, the text hangs off it by the document's unorderedLists.gap, wrapped lines align with the text, and two leading spaces nest a level. So a cell written as • Ofrece elección\n• Acomoda a personas diestras y zurdas comes out as a two-item list.

Column widths belong to the table model, not the style: TableModel.columnWidths is an optional array of relative weights, one per column, normalised at layout time — [2, 1, 1] gives the first column half the width. A missing array, a wrong length, or a non-positive weight falls back to an equal split. The table editor keeps the array aligned when columns are added or removed.

#Caption style

The captionStyle property controls resource captions (the Figure 1 — … line under — or above — images, SVGs, and tables). The numbered label and the description share the same typeface and size — an engine constraint — but the label can carry its own weight, italics, and color. Font family, size, and color inherit the body text when unset. The caption can sit above the resource (the usual convention for tables) and be set on a coloured bar spanning the block width; an optional smaller note (source line, credits — Resource.note) is styled through the note sub-object. A resource type can override any of these fields for its own resources via ResourceType.captionStyle (see Resource types).

const config: PostextConfig = {
  captionStyle: {
    align: 'center',
    labelBold: true,
    labelColor: { hex: '#295AA3', model: 'hex' },
    descriptionItalic: true,
    position: 'above',
    backgroundEnabled: true,
    padding: { value: 0.35, unit: 'em' },
    note: { italic: true, align: 'left' },
  },
};

The note sub-object styles Resource.note, a short run (source, credits, a remark) set under the resource in a smaller size. It accepts the same inline formatting and :ref marks as the caption and inherits the caption typeface. It is placed under the caption when the caption is below, and under the resource body when the caption is above; its height counts towards the block, so a resource with a note floats as one unit.

Per-type overrides are merged with mergeCaptionStyle(resolvedCaptionStyle, override, palette?), exported for hosts that need the same resolution outside the pipeline.

#Diagram style

The diagramStyle property controls how embedded SVG diagrams (kind: 'svg' resources) are coloured. Its single feature today is single-ink mode: a recolouring pass that maps every colour in a diagram to a tint of one ink, so figures reproduce faithfully when the document is printed with a single spot colour.

const config: PostextConfig = {
  diagramStyle: {
    singleInk: true,
    inkColor: { hex: '#295AA3', model: 'hex' },
  },
};

#How single ink works

When singleInk is enabled, every colour in the SVG markup is rewritten to a tint of inkColor whose strength is 1 − relative luminance (Rec. 709 coefficients applied to the gamma-encoded channels — a perceptual approximation that is plenty for tint mapping). The mapping preserves perceived value: white maps to paper white, black maps to the full ink, and light fills stay light regardless of their original hue. A pale yellow background becomes a pale tint of the ink; a dark stroke approaches the full ink.

The recolouring is performed by the exported applySingleInkToSvg(svgText, inkHex), which operates DOM-free on the SVG markup as text:

• #rgb / #rgba / #rrggbb / #rrggbbaa hex literals and rgb() / rgba() functions are rewritten wherever they appear — presentation attributes, inline style, gradients, <defs>.
• The white and black keywords are replaced only where they appear as paint values (fill, stroke, stop-color, flood-color, color — as attributes or inline-style properties), never inside text content or labels.
• none, transparent, and currentColor are left untouched.
• Alpha channels are preserved (#rgba / #rrggbbaa nibbles and rgba(…) alpha components ride along unchanged).
• When inkHex cannot be parsed, the input is returned unchanged.

import { applySingleInkToSvg } from 'postext';
 
const recoloured = applySingleInkToSvg(svgText, '#295AA3');

Single ink applies in all three backends: the canvas viewport and the HTML viewer recolour the SVG markup before rasterising it, and the PDF backend re-rasterizes the SVG resource bytes with the ink applied, so the exported PDF matches the on-screen preview.

Resolver and stripper match the other sections, alongside the DiagramStyleConfig / ResolvedDiagramStyleConfig types:

import {
  DEFAULT_DIAGRAM_STYLE_CONFIG,
  resolveDiagramStyleConfig,
  stripDiagramStyleDefaults,
  applySingleInkToSvg,
} from 'postext';
import type { DiagramStyleConfig, ResolvedDiagramStyleConfig } from 'postext';
 
const resolved = resolveDiagramStyleConfig(config.diagramStyle);
// => { singleInk: false, inkColor: { hex: '#295AA3', model: 'hex', paletteId: 'main-color' } }
 
const minimal  = stripDiagramStyleDefaults(config.diagramStyle);
// => undefined when everything matches the defaults

#Paragraph styles

The paragraphStyles property declares named styles that a document applies to a run of paragraphs with a :::paragraphs{style="…"} container — bibliographies, glossaries, notes, any block of entries that wants its own face, size, leading, or a hanging indent. Every typographic field is optional and inherits the body text when unset, so a style only spells out what differs from running text.

const config: PostextConfig = {
  paragraphStyles: [
    {
      id: 'bibliography',
      name: 'Bibliography',
      fontSize: { value: 7, unit: 'pt' },
      lineHeight: { value: 1.2, unit: 'em' },
      hangingIndent: { value: 2, unit: 'em' },
      spaceBetween: { value: 0.25, unit: 'em' },
      marginTop: { value: 1, unit: 'em' },
      marginBottom: { value: 1, unit: 'em' },
    },
  ],
};

## References
 
:::paragraphs{style="bibliography"}
Knuth, D. E. (1984). *The TeXbook*. Addison-Wesley.
 
Bringhurst, R. (2004). *The Elements of Typographic Style*. Hartley & Marks.
:::

#The :::paragraphs container

A :::paragraphs{style="<id>"} line opens the container and a bare ::: line closes it; every paragraph in between takes the named style, while headings, lists, and other blocks inside keep their usual styling. Containers may be nested inside other fenced containers. An unknown style id is not an error: the paragraphs render as plain body text.

Inside the container the flow leaves the baseline grid — a 7pt entry with 1.2em leading cannot sit on an 8pt/1.5em grid — and the last paragraph snaps the flow back onto it, baking in at least marginBottom below the text (the grid wins; the margin is a minimum, the same convention headings follow). Entries split across columns and pages like body paragraphs, with the same orphan and widow protection; a heading immediately before the container keeps with its first paragraph.

const resolved = resolveParagraphStylesConfig(config.paragraphStyles, resolvedBodyText);
// => every unset field filled from the resolved body text
 
const minimal  = stripParagraphStylesDefaults(config.paragraphStyles);
// => undefined when the list is empty; zero margins and `name === id` dropped

#Chip styles

The chipStyles property declares the named styles of the inline :chip[text]{style="…"} — the rounded, tinted boxes of a word bank, a keyboard key, a tag (the syntax and its line-breaking rules are in the document format reference). One style, chip, ships by default (a pale blue fill with a hairline in the main colour, slightly rounded, the text as the words around it), so :chip[…] works without any configuration; declaring chipStyles replaces that default list. A chip without style, or with an id no style declares, takes the first style.

const config: PostextConfig = {
  chipStyles: [
    { id: 'chip', name: 'Word bank' },
    {
      id: 'key',
      name: 'Keyboard key',
      background: { hex: '#fff4d6', model: 'hex' },
      borderColor: { hex: '#8a6d1f', model: 'hex' },
      borderRadius: { value: 2, unit: 'pt' },
      bold: true,
    },
  ],
};

Classify: :chip[battery] :chip[cable] :chip[switch]
 
Press :chip[Ctrl]{style="key"} + :chip[C]{style="key"}.

Em lengths of the box (paddingX, paddingY, borderRadius, borderWidth, gap) are relative to the chip's own font size. The box is a band 0.8 em above and 0.25 em below the baseline, grown by paddingY and the outline; it paints outside the line box and never changes the leading, so the baseline grid holds. When the box ends up taller than the line pitch the chips of consecutive lines touch — the sandbox lists a "Chips touch the next line" warning with the excess, so paddingY, the outline or fontSize can be reduced.

In the VDT a chip is a line segment of kind: 'chip' whose chip field carries the text runs (each with its font string and width), the box geometry (boxWidth, ascent, descent, paddingX, borderWidth, borderRadius, the gap margins) and its colours; the segment's text is a one-character placeholder, so plain-text offsets and source maps count a chip as one character.

const resolved = resolveChipStylesConfig(config.chipStyles);
// => the built-in `chip` style when unset; every field filled
 
const minimal  = stripChipStylesDefaults(config.chipStyles);
// => undefined for the built-in default; static defaults dropped
 
const style = pickChipStyle(resolved, 'key');
// => the `key` style, else the first one

#Callout styles

The calloutStyles property declares the named box styles a document applies with a :::callout{type="…"} container — notes, tips, warnings, learning objectives, any content set apart from the running text in a tinted or bordered box. One neutral style, note, ships by default (light grey background, no border, no stripe, no icon, no title), so :::callout works without any configuration; declaring calloutStyles replaces that default list.

const config: PostextConfig = {
  calloutStyles: [
    { id: 'note', name: 'Note' },
    {
      id: 'objectives',
      name: 'Learning objectives',
      title: 'Objectives',
      stripe: { enabled: true, side: 'left' },
      icon: { kind: 'glyph', glyph: '✓' },
      titleStyle: { textTransform: 'uppercase' },
      lists: { bulletChar: '–' },
    },
    {
      id: 'warning',
      title: 'Warning',
      backgroundEnabled: false,
      border: { enabled: true, color: { hex: '#AA0000', model: 'hex' }, width: { value: 1, unit: 'pt' } },
      borderRadius: { value: 1, unit: 'mm' },
      titleStyle: { color: { hex: '#AA0000', model: 'hex' } },
    },
  ],
};

:::callout{type="objectives"}
- Describe the parts of the lantern.
- Trim the wick at dusk.
:::
 
:::callout{type="warning" title="Do not touch the lens"}
The glass stays hot for an hour after the flame is out.
:::

#The :::callout container

A :::callout{type="<id>"} line opens the box and a bare ::: line closes it. The fence accepts four attributes — type (the style id), title (overrides the style's title), span and placement (override the style's values) — and the content in between is laid out inside the box: an optional title, then the paragraphs, lists, blockquotes, formulas or resource embeds, each typeset with the style's body / lists typography (headings keep their usual styles). Margins between children collapse as in the running text; the interior leaves the baseline grid, and the flow snaps back onto it after the box with at least marginBottom below (the grid wins; the margin is a minimum — the same convention resources follow). A style with snapToGrid: false keeps the exact marginBottom instead, and the text after the box stays off the grid until the next heading or list end. A heading immediately before a callout keeps with it.

Limits in this version:

• A callout is kept whole unless its style sets keepTogether: false. When it does not fit the remaining column space it moves whole to the next column or page — also out of an empty column that float bands or a band cap have cut short, as long as a full column would hold it. A box taller than a full column splits instead, like a splittable one; only one that no cut can split (a figure, table or :::columns group taller than the column, or a splitMinLines no cut satisfies) is placed anyway and overflows; the layout then records a calloutOverflow warning (VDTDocument.warnings), which the sandbox lists. A splittable box leaves the part that fits behind — whole children, or the lines of a paragraph down to splitMinLines on each side (a figure, table or display formula alone is enough for a side) — and continues in a box without title or icon on the next column or page.
• Floats yield to an unbreakable box. When the block right after a figure's reference is a keepTogether callout, a slot that would leave the box no column of the current band to land in (the referencing column or an empty one after it, which held it before the float) is not taken: the figure moves on to its next slot, usually the next page, and the box stays in flow — as a compositor would set it, rather than pushing the box off the page and leaving the column with the figure alone.
• span: 'page' in a multi-column layout makes the box a span block: it is laid out at the full content width and splits the page into column bands — the text columns above it are closed at the cut line, the box takes its own full-width column, and a fresh band of text columns opens below it, so the flow continues under the box in every column. Where the columns are level — at the top of a page, right below a span: 'page' opener heading, right below another span block, or right below a top float band — the box simply cuts there. Arriving mid-page, with the columns uneven, it is set the way a compositor would: the text above it is cut level across all columns (the engine re-runs placement with the band's columns shortened to the same number of grid lines, so the text overflows from column to column naturally and every orphan, widow and keep-with-next rule still applies), the box spans the page, and the columns resume below it. The cut takes a couple of extra placement passes; when the cut line would leave no room for the box plus the widow minimum of body lines below it, or no arrangement fits after a few attempts, the box moves to the top of the next page. With headings.balancing.beforeSpan (the default) the band it leaves is cut level behind it — like a chapter's closing band — and, when the style allows splitting (keepTogether: false), the part of the box that fits under the levelled columns closes the page and the rest opens the next one; with beforeSpan: false the page it leaves is simply balanced as usual, without forcing a page break. A heading right before a span block does not travel with it. In single-column layouts span: 'page' is simply inline.
• placement: 'fixed' takes the box out of the flow: it is laid out (width: 'auto' shrink-wraps the title; 'fill' takes the width of the text column under the anchor point) and pinned to the page where it occurs in the flow at the position fixed.anchor / fixed.offset describe — the bottom-left corner of the content area by default. The text columns it covers give up that zone (cut from the bottom, or from the top when the column is still empty), exactly like a float band; when the zone already holds text, a float or a span block, the box moves to the next page. A fixed box that closes the chapter (the next block is a chapter opener, a :::part, a float-barrier box or the end of the document) first levels the columns above it (headings.balancing.trailing), so a short closing page ends level with the badge beneath. Frame and children live in page.floats and render outside the column clip in every backend.
• placement: 'top' | 'bottom' floats the box like a resource: it leaves the flow where it occurs and takes the first free band after that point — the foot of the current page ('bottom'), or the head / foot of the next page the flow opens — at the column width (span: 'column') or the full content width (span: 'page'); the text after it fills the page it left. Its frame and children go to page.floats, as a fixed box does. A floated box heading a fresh page is set before the figures waiting for that page, and a figure cited on an earlier page that then fits under it takes the rest of that page even when fewer than three text lines would remain (a gallery page: box plus figure, no text between them). A span: 'side' box never floats: it stacks beside the text whatever its placement.
• width: 'auto' shrink-wraps the title only; children are ignored.
• A :::callout nested inside another callout is a box of its own: it is laid out with its own style (background, border, radius, padding, stripe, title, icon, marker, label, typography) at the full inner width of its parent and stacks as one child of it, its marginTop / marginBottom collapsing with its neighbours. Its span and placement (fence or style) are ignored — a nested box always flows inside its parent — and so are floatBarrier and snapToGrid. Boxes nest to any depth and may sit inside a :::columns group (each one whole, in one column). When the parent splits, the cut falls before or after a nested box, or inside it when the nested style allows splitting; every fragment redraws the frames it cuts through, and a nested box continued from the previous fragment drops its title and icon, like a top-level continuation.
• A :::columns{count=N} … ::: group among the children lays those children out in N columns of equal width, columnGap apart, inside the box: the run is cut at the block or line boundaries that level the columns best (a paragraph or list item cut mid-way continues at the head of the next column without its bullet), every column starts at the group's top and the group is as tall as its tallest column; the children after it return to the full width. A split box (keepTogether: false) never cuts inside a group. Use it for a two-column summary of key points, or the tables of a wide box set side by side.
• The fence's fifth attribute, label, prints on the style's label tab (see label above) — :::callout{type="box" label="BOX 1-1" title="The octet rule"}; without a label style the attribute is ignored.

In the VDT the box is a type: 'callout' frame block whose decoration (background, stripe, icon, title) lives on designOverlay, followed by its child blocks in the same column; the frame and every child carry the fence's containerId. A nested box is a type: 'callout' frame of its own among the children, followed by its blocks; they keep the top-level fence's containerId (placement and balancing still see one unit) and add calloutPath, the container ids of the nested fences around them, outermost first (a nested frame's own id is the last entry). The tagged PDF gives each nested box a Div inside its parent's. Icon images resolve like resource images: the canvas image registry, the HTML resourceImageUrl option and the PDF resourceBytes provider.

const resolved = resolveCalloutStylesConfig(config.calloutStyles, resolvedBodyText, resolvedHeadings, resolvedUnorderedLists);
// => every inherited field filled from the resolved sections
 
const minimal  = stripCalloutStylesDefaults(config.calloutStyles);
// => undefined for the built-in `note` default; static defaults dropped

#Parts

The parts property configures the part-divider pages a document opens with a :::part{number="…" title="…"} container — the “Part I — Foundations” page that groups a run of chapters. A part always occupies a page of its own: the container breaks to a fresh page of the configured parity, converts it into a single-column page whose body area comes from parts.margins, lays the opener design over the whole page, and breaks again after the closing fence so the next chapter (with its own breakBefore.parity) starts clean — with the default H1 settings that yields the classic recto part page, blank verso, chapter on the next recto.

const config: PostextConfig = {
  parts: {
    breakBefore: { parity: 'odd' },
    breakAfter: { enabled: true, parity: 'any' },
    margins: { top: { value: 9, unit: 'cm' }, left: { value: 3, unit: 'cm' }, right: { value: 3, unit: 'cm' } },
    design: {
      elements: [
        {
          kind: 'text', id: 'number', content: 'Part {numberRoman}',
          fontSize: { value: 12, unit: 'pt' }, fontWeight: 600, align: 'left',
          placement: { anchor: { to: 'page', edge: 'top-left' }, offset: { x: { value: 3, unit: 'cm' }, y: { value: 5, unit: 'cm' } }, size: { width: 'auto', height: 'auto' } },
        },
        {
          kind: 'text', id: 'title', content: '{titleText}',
          fontSize: { value: 28, unit: 'pt' }, fontWeight: 700, align: 'left', overflow: 'wrap',
          placement: { anchor: { to: '#number', edge: 'below' }, size: { width: { value: 15, unit: 'cm' }, height: 'auto' } },
        },
      ],
    },
    bodyStyle: { fontSize: { value: 11, unit: 'pt' }, numberColor: { hex: '#AA0000', model: 'hex' } },
  },
};

:::part{number="I" title="Foundations"}
1. The lantern and its parts
2. Trimming the wick
3. Reading the weather
:::
 
# The lantern and its parts

#Part design placeholders

The design slot resolves the heading placeholder set with the part's own values: {titleText} is the fence's title; {number} the number exactly as written; {numberDecimal}, {numberRoman}, {numberRomanLower}, {numberAlpha}, {numberAlphaLower} re-format it — the number is parsed as a decimal or a roman numeral ("IV", "iv" and "4" all give {numberDecimal} = 4), and resolve to '' for anything else. {partTitle} / {partNumber}, {chapterTitle} / {chapterNumber} (the chapter before the part), {pageNumber}, {totalPages} and the metadata placeholders are available too. {attr.<key>} reads the current chapter's H1 attributes.

#The :::part container

A :::part{number="…" title="…"} line opens the part and a bare ::: closes it; both attributes are optional (they default to ''). The blocks in between — typically the chapter list — flow in the part page's single column with bodyStyle, starting at margins.top; a body longer than the page continues on ordinary pages. The page is classified role: 'part' (VDTPage.partInfo carries the number and title), so header and footer elements can target or skip it with pages: 'part' / pages: 'body'; the PDF backend adds the part to the outline above its chapters. An empty body (:::part{…} directly followed by :::) is the common case and still produces the page — consecutive parts never share one. A :::part nested in another part is flattened into the outer one.

A third attribute, palette="<id>=<hex>[, <id>=<hex>…]", gives the part its own colours: on the part page and on every page that follows it — until the next part — each design colour (header, footer, opener band, part and verso designs) linked to one of those palette ids takes the part's value instead of the document palette's. That is how a book's sections recolour the corner tab, the running-head dot and the chapter-opener band without a second design: :::part{number="II" title="…" palette="band=#f6c297"}. The text flow follows too: on the same pages, every flow colour equal to the base value of an overridden palette entry — headings, bold, italic and reference colours, bullets and list numbers, caption labels, table text and rules — takes the part's value, so headings.levels[1].color linked to band sets each section's headings in its own colour. Inline swatches keep the colour written in them. Pairs are separated by commas, semicolons or spaces, = or : joins id and colour, the # is optional. A part stays in effect after its fence closes: {partTitle}, {partNumber} and the palette follow the flow into the chapters after it and — through continuation.part, which continuationAfter() reports — into chapters laid out on their own, so the second chapter of a section shows the section in its running heads exactly as the first does.

const resolved = resolvePartsConfig(config.parts, resolvedPage, resolvedBodyText, resolvedUnorderedLists, resolvedOrderedLists);
// => margins filled from the page, bodyStyle from the body / list configs
 
const minimal = stripPartsDefaults(config.parts);
// => undefined when only static defaults remain

#Heading styles

The headingStyles property declares named styles a document applies to a heading with # Title {style="<id>"}. A style does two things. It overrides the heading's level typography and design — every field of a level entry except level and numberingTemplate (font, size, colour, breakBefore, span, advancedDesign, textTransform…) — and it governs the section the heading opens: its pages, up to the next heading of the same or a higher level, take the style's running heads, page geometry, body typography and palette. That is how a book's front matter (a preface in a single wide column with roman folios and blue bands) sits in a two-column, decimal-numbered manual without a second configuration.

const config: PostextConfig = {
  headingStyles: [
    {
      id: 'front-matter',
      numbered: false,
      breakBefore: { enabled: true, parity: 'odd' },
      span: 'page',
      advancedDesign: { enabled: true, minHeight: { value: 52, unit: 'mm' }, slot: { elements: [/* bands, `{titleText}` */] } },
      header: { elements: [/* folio | rule | `{title}. {subtitle}` */] },
      margins: { left: { value: 50, unit: 'mm' }, right: { value: 17, unit: 'mm' } },
      layout: { layoutType: 'single' },
      bodyStyle: { fontSize: { value: 10.5, unit: 'pt' }, textAlign: 'justify' },
      palette: { band: '#547396' },
    },
  ],
};

# Preface {style="front-matter"}

A section closes at the next heading of the same or a higher level: an unstyled # after a styled one returns to the document's running heads and geometry; a styled one opens its own section. Pages the section left blank for parity belong to it, like chapter titles do.

const resolved = resolveHeadingStylesConfig(config.headingStyles, resolvedPage, resolvedBodyText, resolvedUnorderedLists, resolvedOrderedLists);
// => level overrides normalised, margins filled from the page, bodyStyle from the body
 
const minimal = stripHeadingStylesDefaults(config.headingStyles);
// => undefined when no style remains

#Table of contents

The toc property configures what a :::toc directive prints (see Document format). The contents are assembled from the document's outline — every heading with its number and page label, every :::part — so they follow the chapters: rename one, move it to another part, change its authors, and the entries change with it. An entry is the heading's number in a column of its own, the title, a leader and the page label at the right edge, then an optional subtitle line; a part is a row designed by parts.design.

const config: PostextConfig = {
  toc: {
    levels: [{ level: 1, fontWeight: 700, color: { hex: '#00507b', model: 'hex' }, numberWidth: { value: 7.4, unit: 'mm' } }],
    unnumbered: { color: { hex: '#000000', model: 'hex' } },
    pageNumber: { fontWeight: 400, width: { value: 8, unit: 'mm' } },
    leader: { char: '.', gap: { value: 1, unit: 'mm' } },
    subtitle: { enabled: true, attr: 'author', italic: true, fontSize: { value: 8.5, unit: 'pt' } },
    parts: {
      height: { value: 23, unit: 'pt' },
      marginTop: { value: 11.5, unit: 'pt' },
      design: { elements: [/* a band box, 'SECTION {number}', '{titleText}', '{pageNumber}' */] },
    },
  },
};

The page labels are the ones the document prints. buildDocument() lays a document with a :::toc out again with the labels of the previous pass until they settle (at most three extra passes); a host laying a book out chapter by chapter supplies the whole book's outline as PostextContent.outline instead, assembled from contentOutline() (headings and parts from the text alone) and outlineFromDoc() (the same entries with the page labels of a layout), and lays the contents chapter out again whenever outlineKey() of that outline changes.

#Units and colors

#Dimensions

All physical measurements in Postext use the Dimension type — a value paired with a unit:

interface Dimension {
  value: number;
  unit: DimensionUnit; // 'cm' | 'mm' | 'in' | 'pt' | 'px' | 'em' | 'rem'
}

Absolute units — cm, mm, in, pt, px — are converted to pixels using the configured DPI. At 300 DPI, 1 cm equals approximately 118 px.

Relative units — em, rem — scale with the current font size. An em is relative to the element's own font size; rem is relative to the body text font size.

#Colors

Colors are stored with both a hex representation and a target color model:

interface ColorValue {
  hex: string;        // '#ff0000', 'transparent', etc.
  model: ColorModel;  // 'hex' | 'rgb' | 'cmyk' | 'hsl'
}

The model field indicates the intended color space. For web rendering, 'hex' or 'rgb' are typical. For print workflows, 'cmyk' preserves the intent that the color should be specified in CMYK when exported to PDF.

Because Postext targets publication-grade output, the default body text color ships with model: 'cmyk' (#000000). Heading, bold, italic, and list colors default to the palette-linked Main Color (#295AA3, model: 'hex'). Page background and UI overlays (baseline grid, cut marks, debug indicators) default to model: 'hex'. Override color.model on any field if you need different export semantics.

#Custom fonts

Postext resolves every fontFamily string against both the Google Fonts catalogue and the document's customFonts list. Custom fonts take precedence on name collision — if you declare customFonts: [{ name: 'Roboto', … }], Postext uses your uploaded file instead of the Google Fonts "Roboto".

Use custom fonts when:

• The document needs a brand or licensed typeface that is not on Google Fonts.
• The environment can't reach the Google Fonts CDN (offline, intranet, privacy-sensitive).
• You must keep the font binary private and not upload it to a third party.

#Configuration schema

type CustomFontFormat = 'woff2' | 'woff' | 'ttf' | 'otf';
type CustomFontStyle = 'normal' | 'italic';
 
interface CustomFontVariant {
  weight: number;           // CSS font-weight, 100..900
  style: CustomFontStyle;
  fileId: string;           // opaque id of the binary in out-of-band storage
  format: CustomFontFormat;
  fileName?: string;        // original upload filename (optional, shown in UI)
}
 
interface CustomFontFamily {
  name: string;             // used anywhere a Google Font family name fits
  variants: CustomFontVariant[];
}
 
interface PostextConfig {
  // ...
  customFonts?: CustomFontFamily[];
}

Each variant's binary is not embedded in the config itself. The config only holds fileId pointers; the bytes live out-of-band. In the sandbox, that means IndexedDB (key-value store, browser-only, private to the document). An integrator embedding Postext in another host is free to resolve fileId however they like — a server endpoint, a service worker cache, anything — as long as the bytes reach the main thread before buildDocument runs.

#Managing custom fonts in the sandbox

Open the Fonts panel from the left activity bar (between Resources and Configuration). For each family:

1. Add font family — creates an empty family; rename it inline.
2. Upload variant(s) — pick a weight (100–900) and style (normal / italic), then choose one or many .woff2, .woff, .ttf, or .otf files. Each file becomes its own variant bound to the currently-selected (weight, style); the uploaded filename is remembered and shown in the row so you can tell variants apart. Re-tune a variant's weight or style from its dropdowns at any time.
3. Duplicate variants are allowed. If two files land on the same (weight, style) slot, both are kept and a Duplicate font variant warning appears so you know to disambiguate the settings of the extras.
4. Delete variant or Delete family — removes the entry from the config and the stored bytes from IndexedDB.

Once a family is declared, every font picker groups it under Custom, above the Google Fonts list. Selecting it wires the family into every font-family field you apply it to.

#Rendering behaviour

Under the hood:

• When customFonts changes, every declared family is automatically registered as FontFace entries on document.fonts — so the HTML viewer, the Canvas viewport (which measures through document.fonts), and any direct CSS reference all pick up the custom face without requiring the user to first open the Font Picker.
• The layout worker receives the same ArrayBuffers through the existing font payload transfer path, so measurement (buildFontString, pretext) produces identical metrics to Google Fonts.
• Changing or removing a variant drops the worker's cached face for that family and re-registers on the next build, so previews stay in sync with the current variant set.
• PDF export: uploaded binaries flow through the same PdfFontProvider pipeline. .woff2 files are decompressed; .ttf and .otf are passed through directly. .woff is rejected with a clear error (pdf-lib can't embed raw WOFF — re-upload as .woff2/.ttf/.otf). CFF-flavored OpenType (.otf with OTTO magic) is embedded without subsetting, because pdf-lib's CFF subsetter walks every glyph at save() time and can hang for minutes on real fonts; skipping subset trades a somewhat larger PDF for consistent render times.

#Missing-font warnings

The warnings panel recognises three new failure modes specific to custom fonts (all enabled by the same debug.warnings.missingFont toggle that already guards the generic "not loaded" warning):

• Unknown font family — a fontFamily references a name that is neither a known Google Font nor a currently-declared custom family. This also fires immediately when you delete a custom family that some fontFamily field still references, instead of waiting for the DOM to notice.
• Missing font variant — the family exists but at least one of the standard weight/style slots (400 / 700, normal / italic) has no uploaded file. The warning lists the specific combinations that are missing.
• Duplicate font variant — two or more uploaded files share the same (weight, style) slot within one family. Only one file is actually used at render time; the warning nudges you to retune the remaining entries.

Clicking any of these warnings opens the Fonts panel so you can upload the missing variant, re-add the family, or disambiguate the duplicates.

#Color Palette

The colorPalette property on PostextConfig lets you define a reusable set of named colors and reference them from any ColorValue in the configuration. It is the Postext equivalent of CSS custom properties or an InDesign swatches panel: change the palette entry once, and every color that points to it updates across the document.

interface ColorPaletteEntry {
  id: string;       // stable identifier — referenced by ColorValue.paletteId
  name: string;     // human label shown in sandbox UIs
  value: ColorValue;
}

#The default palette

Postext ships with a single-entry default palette called Main Color (id: 'main-color', hex #295AA3). Several defaults — heading color, bold/italic body color, bullet and number-marker colors — reference this entry via paletteId: 'main-color', so changing that one swatch retints every part of the document that uses it.

You can inspect, clone, or compare against the default palette via three exports:

import {
  DEFAULT_COLOR_PALETTE,
  cloneDefaultColorPalette,
  isDefaultColorPalette,
} from 'postext';
 
// Read-only snapshot of the shipped palette.
DEFAULT_COLOR_PALETTE;
// => [{ id: 'main-color', name: 'Main Color', value: { hex: '#295AA3', model: 'hex' } }]
 
// Independent copy — mutate this, not DEFAULT_COLOR_PALETTE.
const palette = cloneDefaultColorPalette();
 
// Detect whether a user has customised the palette at all.
isDefaultColorPalette(palette); // true

A palette lives at the top level of the config:

const config: PostextConfig = {
  colorPalette: [
    { id: 'ink',    name: 'Ink',    value: { hex: '#0a0a0a', model: 'cmyk' } },
    { id: 'accent', name: 'Accent', value: { hex: '#b8860b', model: 'hex' } },
  ],
  bodyText: { color: { hex: '#000000', model: 'cmyk', paletteId: 'ink' } },
  headings: { color: { hex: '#000000', model: 'hex', paletteId: 'accent' } },
};

#Referencing a palette entry

Any ColorValue in the configuration — page background, body text color, heading colors, column rules, list colors, task-completed color, cut-mark color, baseline-grid color, debug indicators — can carry an optional paletteId field pointing at an entry in colorPalette. When present, the palette entry's hex / model win over the fallback hex / model stored alongside. The inline fallback is only used if the palette is missing, empty, or doesn't contain that id — useful when shipping a config that will be read by a tool that doesn't understand palettes.

#How palettes are applied

buildDocument runs the palette in two places so referenced colors work both for overrides you spelled out and for defaults that are filled in later:

1. applyPaletteToConfig(config) — flattens every ColorValue in the raw user config that carries a paletteId. Useful when you want to inspect what the engine will actually see.
2. applyPaletteToResolvedConfig(resolved, palette) — runs after defaults are resolved and rewrites the palette-linked defaults (heading color, bold/italic body color, list colors) to match the active palette.

You rarely need to call these yourself, but both are exported so you can inspect or reuse them:

import {
  applyPaletteToConfig,
  applyPaletteToResolvedConfig,
  resolveColorValue,
} from 'postext';
 
const flat = applyPaletteToConfig(config);
// Every ColorValue with a paletteId in the raw config has been replaced
// with the palette entry's hex/model.
 
// `applyPaletteToResolvedConfig` is typically handled by buildDocument; use it
// directly if you build a ResolvedConfig yourself and want the palette applied.

resolveColorValue(value, palette, fallback) is the single-value variant, handy when you are composing configs imperatively and need to resolve one color at a time.

#Editing the palette

Removing a palette entry should go through unlinkPaletteRefs (exported from postext-sandbox) so that any ColorValue still pointing at the removed id gets rewritten with the plain hex / model fallback. The sandbox's "Color Palette" section does this automatically.

#HTML Viewer

The htmlViewer property controls how the HTML backend lays out pages on screen. It only applies when you render with renderToHtml / renderToHtmlIndexed; the canvas and PDF paths ignore it entirely — they consume the configured page.width, page.height, and page.dpi directly.

interface HtmlViewerConfig {
  maxCharsPerLine?: number;     // Target column width, in characters of the body font.
  columnGap?: number;            // Horizontal gap between columns in multi-column mode (px).
  optimalLineBreaking?: boolean; // Use Knuth–Plass inside the HTML viewer instead of greedy.
  overrides?: HtmlViewerOverrides; // Screen-only partial config merged over the document config.
}
 
type HtmlViewerOverrides = Omit<PostextConfig, 'htmlViewer'>;

const config: PostextConfig = {
  headings: { levels: [{ level: 1, span: 'page', breakBefore: { enabled: true } }] },
  htmlViewer: {
    // On screen, chapters flow on without the page-span opener.
    overrides: { headings: { levels: [{ level: 1, span: 'column', breakBefore: { enabled: false } }] } },
  },
};

Resolver and stripper follow the same pattern as the other sections:

import {
  DEFAULT_HTML_VIEWER_CONFIG,
  resolveHtmlViewerConfig,
  stripHtmlViewerDefaults,
} from 'postext';
 
const resolved = resolveHtmlViewerConfig(config.htmlViewer);
// => { maxCharsPerLine: 70, columnGap: 50, optimalLineBreaking: false }
 
const minimal = stripHtmlViewerDefaults(config.htmlViewer);
// => undefined when everything matches the defaults

See Integrating the HTML viewer below for an end-to-end example.

#PDF generation (config)

The pdfGeneration property controls how the PDF backend emits the final document. These settings are consumed by the postext-pdf package at export time; the canvas and HTML viewers ignore them.

type PdfColorSpace = 'rgb' | 'cmyk' | 'grayscale';
 
interface PdfGenerationConfig {
  outlines?: boolean;          // Emit PDF bookmarks from the heading tree.
  forceColorSpace?: boolean;   // Convert every colour to `colorSpace`.
  colorSpace?: PdfColorSpace;  // Target space used when `forceColorSpace` is true.
  accessible?: boolean;        // Tagged, PDF/UA-oriented output (structure tree, alt text, language).
}

pdfGeneration: {
  outlines: true,
  accessible: true,
  forceColorSpace: true,
  colorSpace: 'cmyk',
}

Resolver and stripper match the other sections:

import {
  DEFAULT_PDF_GENERATION_CONFIG,
  resolvePdfGenerationConfig,
  stripPdfGenerationDefaults,
} from 'postext';
 
const resolved = resolvePdfGenerationConfig(config.pdfGeneration);
// => { outlines: true, forceColorSpace: false, colorSpace: 'cmyk', accessible: true }
 
const minimal  = stripPdfGenerationDefaults(config.pdfGeneration);
// => undefined when everything matches the defaults

See Generating PDFs below for the end-to-end export recipe.

#Debug

The debug property groups two kinds of authoring aids: visual overlays that keep the source text and the rendered layout in sync, and a set of warnings that surface typographic or structural problems in the editor's warnings panel. Neither affects exported output.

#Visual overlays

Each SyncIndicatorConfig is { enabled: boolean; color?: ColorValue }. LooseLineHighlightConfig is { enabled: boolean; color?: ColorValue; threshold?: number }. pageNegative is a minimal { enabled: boolean } toggle.

debug: {
  cursorSync: { enabled: true, color: { hex: '#ff0066', model: 'hex' } },
  selectionSync: { enabled: false, color: { hex: '#fde04780', model: 'hex' } },
  looseLineHighlight: { enabled: true, color: { hex: '#ff000040', model: 'hex' }, threshold: 3 },
  pageNegative: { enabled: true },
}

#Warnings

debug.warnings controls which authoring issues appear in the editor's warnings panel. Each key is an independent boolean toggle; set one to false to silence that specific warning without disabling the others.

interface WarningsToggleConfig {
  missingFont?: boolean;
  looseLines?: boolean;
  headingHierarchy?: boolean;
  consecutiveHeadings?: boolean;
  listAfterHeading?: boolean;
  designIssues?: boolean;
}

debug: {
  warnings: {
    missingFont: true,
    looseLines: true,
    headingHierarchy: true,
    consecutiveHeadings: true,
    listAfterHeading: false,
    designIssues: true,
  },
}

#Programmatic Usage

Recommended path: use the Web Worker. In a browser, the overwhelming majority of integrations should drive the layout pipeline through createLayoutWorker() from postext/worker, not by calling buildDocument directly on the main thread. The worker keeps the UI responsive during builds, caches text measurements across incremental rebuilds, and wires up last-wins cancellation so a new keystroke aborts any stale build already in flight. Jump straight to Running layout in a Web Worker for the canonical recipe. Everything in the rest of this section (direct buildDocument, resolvers, strippers, caches) is still useful — the worker exposes the exact same inputs and outputs — but for UI code the worker wrapper is the correct starting point. Only fall back to calling buildDocument on the main thread for one-shot exports, server-side rendering (Node), or tests.

#Building a document

The buildDocument function runs the full layout pipeline and returns a Virtual Document Tree (VDT) with precise coordinates for every element. This is the lowest-level entry point; UI code should prefer the Web Worker wrapper, which calls buildDocument inside a dedicated worker thread with the same arguments.

import { buildDocument } from 'postext';
 
const content = {
  markdown: '# Chapter One\n\nThe story begins here...',
};
 
const config = {
  page: { sizePreset: '17x24' },
  layout: { layoutType: 'double' },
  bodyText: { fontFamily: 'EB Garamond', fontSize: { value: 9, unit: 'pt' } }, // 9 pt overrides the 8 pt default
};
 
// Build the layout — produces a VDT with one entry per page in `vdt.pages`
const vdt = buildDocument(content, config);
console.log(`Document has ${vdt.pages.length} pages`);

#Rendering a page to a bitmap

Each page can be rasterized independently. Use renderPage(page, doc) to obtain an HTMLCanvasElement for a given page number — the canvas is a bitmap sized exactly to the page dimensions in pixels (at the configured DPI), so you can display it, export it, or feed it into any image pipeline:

import { buildDocument, renderPage } from 'postext';
 
const vdt = buildDocument(content, config);
 
// Render page 3 (zero-indexed) to a bitmap canvas
const pageNumber = 2;
const page = vdt.pages[pageNumber];
if (!page) throw new Error(`Page ${pageNumber} does not exist`);
 
const canvas = renderPage(page, vdt);
// canvas.width / canvas.height are the page bitmap size in pixels
 
// Show it in the DOM
document.body.appendChild(canvas);
 
// …or export it as a PNG data URL
const pngDataUrl = canvas.toDataURL('image/png');
 
// …or get a Blob for download / upload
canvas.toBlob((blob) => {
  if (blob) saveAs(blob, `page-${pageNumber + 1}.png`);
}, 'image/png');
 
// …or grab raw RGBA pixels
const ctx = canvas.getContext('2d')!;
const imageData = ctx.getImageData(0, 0, canvas.width, canvas.height);