Architecture

DocForge implements the Pandoc route below. The native renderer is not built (see the roadmap).

Pipeline

Document JSON (+ template it names) ─► strict Zod schema ─► typed document model (IR)
   ─► HTML renderer (shared CSS/tokens)  ─► browser preview
   ─► lint (structure, tables, images, fonts)
   ─► DOCX renderer
        Today:     HTML ─► gordon-doc (Pandoc + reference.docx) ─► DOCX
        If needed: IR ─► `docx` (npm) native renderer ─► DOCX
   ─► preview: DOCX ─► PDF ─► PNG pages (gordon-doc / LibreOffice)

The document model (IR) is the stable center. Input formats and output renderers are adapters, so PDF or Markdown renderers can be added later.

Content model

Block types: heading(1-3), paragraph, list(ordered|bullet, nested), table, image(+caption, alt), quote, code, pageBreak, toc, callout. Document metadata: title, author, language, page size, margins, header/footer text, page numbers. Inline: bold, italic, code, link, footnote.

Templates and tokens

A template is a set of tokens (fonts including East Asian, sizes, colors, page margin). After gordon-doc converts the HTML, src/exporters/style.ts writes the tokens into the DOCX styles.xml (defaults, Normal, Heading 1–4, TOC heading, hyperlink) and pgMar. Table borders, code backgrounds and list indents still come from the converter.

Source map

Path Responsibility
src/schemas/document.ts Strict Zod schema and parseDocument
src/validators/lint.ts Lint rules with machine-readable issues
src/renderers/html.ts Document → HTML (export markup or browser preview)
src/templates/default.ts Design tokens and preview CSS
src/exporters/gordon-doc.ts Locating and running gordon-doc and Pandoc
src/exporters/docx.ts Export, DOCX verification, preview (PDF + PNG)
src/cli/index.ts init, check, build, export, preview
src/exporters/style.ts Applies template tokens to DOCX styles and margins
skills/docforge/ AI authoring skill

Known pitfalls to design for