API Reference

API Reference

The public entry points of every package, grouped by task. Types (PostextConfig, PostextContent, VDTDocument, …) are exported beside the functions; their fields are documented in Configuration and Architecture. How the pieces fit together is in Programmatic Usage.

The surface of postext is checked by packages/postext/src/__tests__/exports.test.ts: an export added or removed without updating it fails CI.

---

postext

Layout

Export	Description
buildDocument(content, config?, cache?, options?)	Parses, measures and lays out a document; returns a VDTDocument. content is { markdown, resources?, metadata?, continuation? }; a continuation lays a chapter out after the previous one. cache is a measurement cache; options include a cancellation hook.
continuationAfter(content, config?, before?)	The continuation the next chapter starts from: counters, the open part, footnote numbers. Page number and parity come from the previous layout.
BuildCancelledError	Thrown when a build is cancelled.
createMeasurementCache(), clearMeasurementCache()	Reuse measurements between builds.
contentOutline, computeOutline, outlineFromDoc, tocOutline, indexOutline	The book outline that feeds :::toc and :::index.
collectContentWarnings(markdown, config?, resources?), collectConfigWarnings(config), formatWarning(w)	Layout and configuration warnings.

Rendering

Export	Description
renderPage(page, doc, options?)	One page on a new <canvas>.
renderPageToCanvas(page, doc, canvas, options?)	One page on a canvas you own.
renderToCanvas(doc, options?)	Every page, one canvas each.
registerResourceImage(fileId, image) and friends	Pictures for the canvas renderer.
renderToHtml(doc, options?)	Absolutely positioned HTML. Options include resourceImageUrl(fileId).
renderToHtmlIndexed(doc, options?)	HTML plus a per-page, per-block index for patching a live view.
findLooseLines, drawLooseLines	The loose-line overlay for your own canvas.
applySingleInkToSvg(svgText, inkHex)	Recolours an SVG to tints of one ink.

Parsing and models

Export	Description
parseMarkdown(markdown), parseMarkdownWithIssues	Markdown to content blocks.
extractFrontmatter(markdown)	YAML frontmatter and the remaining text.
parseTSV, mergeCells, addRow, setCellImage, tableGridIssues, …	Build and check table models.
parseBibtex(text)	BibTeX to CSL-JSON references.

Configuration

Export	Description
resolve<Section>Config(partial)	The full settings of one section with defaults filled in: resolvePageConfig, resolveLayoutConfig, resolveBodyTextConfig, resolveHeadingsConfig, resolveFootnotesConfig, resolveCjkConfig, resolveFolioConfig, …
strip<Section>Defaults(resolved), stripConfigDefaults(config)	The reverse: only what differs from the defaults.
DEFAULT_* constants	The defaults themselves (DEFAULT_PAGE_CONFIG, DEFAULT_CALLOUT_STYLES, DEFAULT_COLOR_PALETTE, …).
PAGE_SIZE_PRESETS	Named page sizes.
defaultResourceTypes(locale)	Figure and Table types in the document's language.
applyPaletteToConfig(config)	Resolves palette references.

Language and script

Export	Description
DOCUMENT_LANGUAGES, directionOf, defaultNumeralsFor, stringsFor	Document languages and what they imply.
hyphenateText, setHyphenationLocale, HYPHENATION_LOCALES, matchHyphenationLocale	Hyphenation.
formatNumeral, buildPageLabels	Numbering styles and page labels.
resolveParagraph, visualOrder, …	The bidirectional algorithm.
setCjkLineBreak, setCjkComposition, cjkRegionOf	East Asian composition.

Maths

Export	Description
initMathEngine()	Loads MathJax (bundled); await it before building a document with $…$.
isMathReady(), onMathReady(cb), renderMath, clearMathCache()	Engine state and cache.

Citations

Export	Description
registerCitationEngine(engine)	Installs a citation engine (what postext-citeproc/register does).
setCitationEngineLoader(load)	Loads one only when a document cites.

Bundles

openBundle, createBundle, buildBundle, loadBundleFonts, registerBundleImages, bundleImageUrl, bundleResourceBytes, bundleFontProvider, POSTEXT_EXTENSION; see postext/bundle below.

---

postext/worker

Export	Description
createLayoutWorker(options?)	Returns a LayoutWorkerHandle: registerFonts(faces), unregisterFonts(families), build(content, config, { signal }), warm(…), dispose(). A newer build with an aborted signal rejects the old one with AbortError.
documentFontFamilies(doc), unavailableFontFamilies(…)	Which fonts a document needs and which are missing.

postext/worker/entry is the worker script. See Running layout in a Web Worker.

postext/bundle

Everything about .postext files: openBundle(bytes), createBundle(book), buildBundle(bundle), the adapters above, readBundle, planBundle, openBundleZip, zipBundle, and the migrations migrateConfig(config) and CONFIG_VERSION. See Bundles.

postext/react

createLayout(content, config?) returns a component that lays the document out when it mounts and shows each page as a canvas. See React.

---

postext-pdf

Export	Description
renderToPdf(doc | docs, options)	PDF bytes. Options: fontProvider (required), resourceBytes, outlines, accessible, colorSpace, characterGrid, onProgress, onWarning, harfbuzzWasm.
decompressWoff2(bytes)	WOFF2 to TTF bytes.
svgToVectorDrawing(svg)	The vector subset used for SVG figures.
createPdfWorker() (postext-pdf/worker)	The same render on a worker.

postext-epub

Export	Description
renderToEpub(chapters, options)	EPUB bytes. Options: layout: 'fixed' | 'reflowable', metadata, fonts, cover, resource bytes.
readEpub(bytes)	Reads an EPUB back, for viewers.
createEpubWorker() (postext-epub/worker)	The same on a worker.

postext-folio

Export	Description
createFolioFromDocument(container, doc, options?)	A 3D book from a laid-out document.
createFolio(container, options)	A 3D book from page images or canvases.
PageFlipper, FlatPageFlipper, spreadsOf, paperSpec, FOLIO_CSS	The pieces underneath.

postext-citeproc

Export	Description
postext-citeproc/register	Side-effect import that registers the engine.
createCiteprocEngine(sources)	An engine with your own styles and locales.
STYLES, LOCALES, STYLE_CATALOG	What is bundled.