Paged — the IDML reference and the Paged docs

The source of two sites, built from one app (ADR 805):

• idml.paged.media: an independent, living reference for the IDML file format (content/docs/idml, pnpm dev:idml).
• docs.paged.media: the documentation of Paged, the open-source engine, SDK, scripting layer and plugins (content/docs/paged, pnpm dev).

Authored from first principles — from small files we build ourselves and from what the renderer learns reading them.

Paged is a native renderer for paged media, starting with IDML — a separate project from the CSS-based Paged.js polyfill.

IDML is a published file format owned by its vendor. This documentation is an independent description by the Paged project and is not affiliated with or endorsed by the vendor.

Documentation of this repository

docs/ documents how the site itself is built; the site's content is in content/docs/.

• docs/concept.md: what the site is for and the rules it follows.
• docs/architecture.md: the build, the generated pages, the examples pipeline, hosting.
• docs/status.md: what ships today and what does not.
• docs/adr/: the architecture decisions, one per file.

Stack

Fumadocs (Next.js App Router + MDX) + TypeScript + pnpm. A single Next app at the repo root.

pnpm install     # generates the Fumadocs source index (postinstall)
pnpm dev         # http://localhost:3000
pnpm build
pnpm typecheck

Repo map

Path	What
content/docs/	The reference. 27 sections, ordered by reader progression (not the spec's order). Each page declares one tier + one Diátaxis mode.
examples/	First-class examples as hand-authored, unzipped IDML XML parts. Imported into MDX; validated against the real renderer in CI.
components/mdx/	The example views (raw / annotated / tree), the difficulty label, and ExampleEmbed (with a reserved WebGPU live slot).
lib/, app/	Fumadocs source loader, the App Router shell, sitemap/robots, the WIP banner, analytics.
scripts/examples/	The UCF-faithful package assembler and the validation gate.
cleanroom/	The masked-prose similarity check (baseline held privately, never in this repo).
core.pin, ownership.yaml	The pinned core commit examples validate against; the crate→doc ownership map.

How it stays honest

• Examples in CI. Every example is assembled into an .idml and validated by paged-inspect (built from core at core.pin). If the renderer stops accepting an example, the build breaks. See examples/README.md.
• Clean-room. No copying the spec — in wording or arrangement. Every content change confirms it; CI runs a masked-prose similarity backstop. See content/docs/idml/meta/clean-room-protocol.mdx.
• Public and indexed. Every page is in the sitemap, drafts included; each site has its own canonical URLs, sitemap and redirects.

Licensing

• Documentation content (content/, examples/): CC BY 4.0 (LICENSE-CONTENT).
• Site code, components, configuration: MIT (LICENSE-CODE).

Both are recommended defaults pending a short pre-launch legal review.

Contributing

Open a content change; the content PR template carries the page contract and the clean-room confirmation. Section owners are in OWNERSHIP.md.