@xemahq/document-renderer

Deterministic document assembler for structured content

Overview

Turns structured content blocks (or Markdown) and a render style into a paginated document: section numbering, table of contents, running headers and footers and page-break control. It returns self-contained print-ready HTML and a normalized DocumentModel tree for other renderers. It is pure: no network, clock or randomness, so the same input always yields the same output.

When to use it

• You need to produce a printable document (for example PDF through a browser print path) from content an agent or service authored.

Installation

pnpm add @xemahq/document-renderer

Usage

import { assembleDocument, BlockKind } from '@xemahq/document-renderer';

const { html, model, pdfHeaderTemplate, pdfFooterTemplate } = assembleDocument({
  title: 'Quarterly Report',
  blocks: [
    { kind: BlockKind.Toc },
    { kind: BlockKind.Heading, level: 1, text: 'Overview' },
    { kind: BlockKind.Paragraph, runs: [{ text: 'Hello ' }, { text: 'world', bold: true }] },
    { kind: BlockKind.PageBreak },
  ],
});

Block kinds: heading, paragraph, list, table, image, callout, page_break, toc, key_value. A malformed block tree throws a typed DocumentRenderError naming the offending path.

Markdown can be used instead of hand-written blocks:

import { parseMarkdownToBlocks, assembleDocument } from '@xemahq/document-renderer';

const blocks = parseMarkdownToBlocks('# Overview\n\nA paragraph with **bold**.');
const { html } = assembleDocument({ title: 'Report', blocks });

It supports headings, paragraphs with inline marks, nested lists, pipe tables, standalone images, blockquotes and alerts, fenced code and thematic breaks. Unsupported constructs (raw HTML, setext headings, footnotes, frontmatter and others) throw DocumentRenderError; pass { onUnsupported: MarkdownUnsupportedMode.Paragraph } to emit them as literal paragraphs instead.

Configuration

assembleDocument({ title, blocks, theme? }). theme is a DocumentRenderStyle (page size and margins, typography, heading styles, header and footer templates with the tokens {pageNumber}, {totalPages}, {title} and {sectionTitle}, TOC style, numbering). It defaults to DEFAULT_RENDER_STYLE.

License

Apache-2.0 © Xema — xema.dev