Project Structure

Project Structure

Postext is a pnpm + Turborepo monorepo. The engine, its output packages, the Sandbox, the website, the Cookbook and the agent skill live in one repository and build together.

postext/
├── apps/
│   └── web/                  # Next.js site: landing, docs, Sandbox, Cookbook, glossary (postext.dev)
├── packages/
│   ├── postext/              # Layout engine (npm: postext)
│   ├── postext-pdf/          # PDF writer (npm: postext-pdf)
│   ├── postext-epub/         # EPUB 3 writer (npm: postext-epub)
│   ├── postext-folio/        # 3D book viewer (npm: postext-folio)
│   ├── postext-citeproc/     # CSL citations (npm: postext-citeproc)
│   ├── postext-sandbox/      # Sandbox editor as a React component
│   └── typescript-config/    # Shared strict TSConfig presets
├── docs/                     # MDX docs, <topic>-<locale>.mdx in en, es, ca, zh, ar
│   └── examples/             # Runnable examples embedded in the docs as CodePens
├── cookbook/                 # Cookbook recipes, one folder each, plus registries and the pen kit
├── plugins/postext/          # Agent skill postext-port (Claude Code plugin and skills.sh)
├── .claude-plugin/           # Claude Code plugin marketplace manifest
├── scripts/presets/          # Showcase book pipelines and the layout regeneration used by releases
├── patches/                  # pnpm patches (wawoff2)
├── .github/workflows/        # CI, Release, showcase layouts
├── turbo.json                # Task pipeline
└── pnpm-workspace.yaml       # Workspace definition

Apps

App

Purpose

apps/web

Next.js 16 + Tailwind CSS 4 site at postext.dev, in English, Spanish, Catalan, Simplified Chinese and Arabic (next-intl). Hosts the docs (rendered from docs/), the Sandbox, the Cookbook (rendered from cookbook/), the glossary, the accessibility statement, Markdown versions of every page (/<locale>/<page>.md, llms.txt, llms-full.txt) and the showcase bundles (public/presets). Scripts: scripts/cookbook (the pnpm cookbook tool) and scripts/wiki (this wiki's generator).

Packages

Package	Published as	Purpose
packages/postext	postext	Semantic content in, layout geometry out; canvas and HTML renderers, worker, bundles, React.
packages/postext-pdf	postext-pdf	PDF from the same layout.
packages/postext-epub	postext-epub	EPUB 3, fixed layout or reflowable.
packages/postext-folio	postext-folio	3D book viewer.
packages/postext-citeproc	postext-citeproc	Citation engine with bundled CSL styles and locales.
packages/postext-sandbox	(not published)	The Sandbox UI: library, editor, panels, previews, storage.
packages/typescript-config	(internal)	Shared TypeScript configuration.

See Packages for entry points and API Reference for exports.

Inside the engine

The main folders of packages/postext/src:

Folder	Role
parse/	Markdown, directives, inline marks, citations and index marks to content blocks.
measure/	Text measurement through Pretext, rich text, hyphenation hooks, the measurement cache.
knuthPlass/	Line breaking.
pipeline/	build.ts (the orchestrator) and the passes: placement, floats, tables, callouts, footnotes, balancing, outlines, citations.
defaults/	Defaults, resolvers and strippers for each configuration section.
design/	Header, footer and opener design slots.
table/	Table models and editing helpers.
math/	MathJax integration.
citations/	The citation engine registry and BibTeX reader.
canvas-backend/, html-backend.ts	The two built-in renderers.
bundle/	.postext files.
worker/	The layout worker and its client.
react/	postext/react.
types.ts, vdt.ts	Configuration and content types; the Virtual Document Tree.

Tech stack

• Package manager: pnpm (the version is pinned in package.json)
• Task runner: Turborepo 2.9
• Language: TypeScript, strict, ESM only
• Tests: Vitest in every package and in apps/web
• Site: Next.js 16, Tailwind CSS 4, MDX, next-intl, Shiki, @base-ui/react for the Sandbox controls
• Engine: @chenglou/pretext, Hypher and TeX patterns, MathJax, gray-matter, fflate
• PDF: pdf-lib, @pdf-lib/fontkit, wawoff2, HarfBuzz (for Arabic shaping)
• 3D: three.js

Build pipeline

Task	Depends on	Notes
build	^build	Packages build before the site. Cached.
dev	^build	Library watchers plus the Next.js dev server. Not cached.
test	^build	Vitest.
check-types	^build	tsc --noEmit.
lint	—	ESLint.

Documentation sources

• docs/*.mdx drive the docs at postext.dev/en/docs, one file per topic and locale (configuration-en.mdx, configuration-es.mdx, …).
• This wiki: the doc pages are generated from the English MDX (see Updating the wiki); Home, Features, Getting Started, Packages, API Reference, this page, Development Setup, Roadmap and Cookbook and Showcase are written by hand.
• Package READMEs are what npm shows.

Adding a package or a top-level folder

1. Register it in pnpm-workspace.yaml (anything under apps/ or packages/ already is).
2. Add tasks to turbo.json if it brings new ones.
3. If it is published, add its bump, build, test and publish steps to the Release workflow (.github/workflows/release.yml).
4. Update this page, Packages and the root README.md.