Documentation Guides

Hands-on guides covering installation, architecture, accessibility, and common questions. For the full API surface, see the API reference in the README.

Local preview: guide pages load markdown via fetch() and require a server. Run cd docs && npx serve . then open localhost:3000/guides/.

• Onboarding → 90-second start for the full ecosystem — the library, pdfnative-cli, pdfnative-mcp, and pdfnative-react. Install + first call for each.
• Quick Start → Install pdfnative and generate your first PDF in Node.js or the browser in under a minute.
• Architecture → Two builders, generation pipeline, module dependency flow, and key design decisions.
• AI governance & HITL → How pdfnative governs AI coding agents — a machine-readable contract and a human-in-the-loop protocol that keep agents as draftsmen. Humans review, approve, and submit everything. Six mandatory rules, compliance report, verify-issue.mjs gate. New in v1.5.0.
• Agentic workflows → Two factual patterns for driving pdfnative from AI agents — extend the engine at runtime by registering fonts without a release (registerFont + parseFontData / compileFontData), and pipe agent-generated images into the PDF via the image block and the embed_image MCP tool. Built on public, validated APIs.
• FAQ → Custom fonts, PDF/A variants, encryption, BiDi, browser/Deno/Bun, signatures, workers, and comparison with other libraries.
• Troubleshooting → Fixes for missing glyphs, RTL text appearing backwards, PDF/A validation failures, oversized PDFs, parser errors.
• Accessibility → Tagged PDF, structure tree, /ActualText, PDF/UA, PDF/A — building accessible PDFs that screen readers and archive validators accept.
• PDF/A conformance → PDF/A-1b, 2b, 2u, 3b — full veraPDF conformance with the v1.1.0 Latin font embedding and XMP parity fixes.
• Digital signatures → CMS/PKCS#7 detached signatures — RSA + ECDSA P-256, one-call addSignaturePlaceholder() workflow, Adobe Reader / openssl-cms validation.
• Smart tables → Multi-page tables — auto-wrap, repeated headers, zebra striping, captions, smart auto-fit columns. Planner-driven architecture, byte-identical to v1.1.0 on unchanged input.
• Colour emoji → v1.3.0 COLRv1 colour emoji — opt-in Noto Color Emoji subset, solid + linear + radial gradient layers rendered as native PDF Form XObjects. Monochrome fallback when not registered.
• Colour-emoji font CLI → v1.4.0 pdfnative-build-emoji-font — bundled CLI that generates a colour-emoji data module with exactly the glyphs you need, from a few codepoints to the full ~3,600-glyph set. --download + checksum, --ttf, --all, --ranges.
• Streaming output → v1.3.0 true constant-memory streaming — buildDocumentPDFStreamTrue() yields chunks while freeing each part, so the full PDF binary never materialises. Plus fixed-size and object-boundary variants, and the new v1.4.0 streamToFile() disk drain.
• Outlines & page labels → v1.4.0 navigable bookmarks (/Outlines) — explicit nested tree or outline: 'auto' from headings — and logical page numbering (/PageLabels): roman front matter, prefixed appendices, custom starts.
• PDF manipulation → Page-tree API — mergePdfs(), splitPdf(), extractPages(). Production-safe clean object-graph rebuild. v1.6.0: decrypts encrypted sources ({ bytes, password }) and adds constant-memory streaming variants (streamMergedPdfs / streamSplitPdf).
• Form filling & flattening → v1.6.0 read, fill, and flatten existing AcroForm PDFs — readFormFields(), fillForm() (regenerated appearances), flattenForm() — via non-destructive incremental update that preserves prior signatures.
• Charts (native vector) → v1.6.0 bar, horizontal-bar, line, pie, and donut chart blocks rendered as pure PDF path operators — zero dependencies, multi-series, "nice" axis ticks, negative values, tagged /Figure + alt text, PDF/A-safe.
• Text extraction → v1.6.0 extractText() — per-page reading-order Unicode text plus positioned runs from any PDF, including encrypted ones. /ToUnicode CMap, /Differences, and WinAnsi/MacRoman decoding; hard memory caps for untrusted input.
• Viewer preferences → v1.4.0 viewerPreferences — control how a reader presents the document on open: page layout, page mode, full-screen kiosk, fit/centre window, reading direction, print scaling. PDF/A-safe.
• Font-data validation → v1.4.0 opt-in validateFontData() — structurally check custom font modules (SFNT magic, base64, cmap coverage, glyph-id range, finite metrics) and get { valid, errors, warnings }.
• Layout debugging → v1.5.0 opt-in visual overlay (layout: { debug: true }) drawing margin / content / cell boxes, plus inspectDocumentLayout() for programmatic per-page block geometry. Byte-identical when off.
• Annotations → v1.5.0 typed markup annotations — text, highlight, underline, strikeout, squiggly, square, circle, line, freetext — with buildAnnotation(), getAnnotations() to read existing PDFs, and addAnnotation() incremental write.
• MCP Integration → Use pdfnative from Claude Desktop, Cursor, Continue, and Zed via pdfnative-mcp — 19 tools (incl. page-tree merge_pdfs, split_pdf, extract_pages, markup annotate_pdf, the network-free draft_governance_issue, plus validate_pdf, verify_pdf, extract_attachments), pdfA flag, multi-script lang, and a signed-document workflow.
• CLI → pdfnative-cli — render, sign, inspect, verify, merge / split / extract, annotate, govern, batch, and emit JSON Schemas from the terminal. Stdin/stdout pipelines, constant-memory streaming, PDF/UA & PDF/A checks, PAdES-T verification, secret-safe signing, and an agent-native --json/E_*/--dry-run contract.
• React → pdfnative-react — build PDFs declaratively with JSX. A custom React reconciler compiles <Document>/<Table>/<Barcode> on-device to pdfnative blocks. Live-preview hooks, streaming, and a token-frugal DocSpec. React 19 peer dep on the React package only — the engine stays zero-dependency.

Looking for samples?

The repository ships with 44 generator categories producing ~227 sample PDFs covering every feature: financial statements, multi-language documents, barcodes, SVG, watermarks, forms, encryption, signatures, streaming, parser, smart tables, outlines & page labels, PDF manipulation, viewer preferences, font validation, math symbols, layout debugging, annotations, form fill/flatten, charts, and stress tests.

Interactive playgrounds

• Extreme scripts playground → Stress-test BiDi (Arabic + Hebrew + Thai), Tamil deep conjuncts, Bengali & Devanagari reph + ligature chains, and isolated Arabic harakat directly in the browser.
• All 22 scripts + emoji → The flagship showcase: render a single PDF spanning every Unicode script pdfnative supports — Latin to CJK, Arabic, Indic, Thai — plus native COLRv1 colour emoji.
• PDF Toolkit → Exercise the v1.4.0 document features — outline bookmarks, page labels, viewer preferences, nested lists, table cell borders, merge / split / extract — plus the v1.6.0 round trip: encrypted AcroForm fill & flatten, AES-256 re-encryption, and text extraction, all client-side.
• Charts → The v1.6.0 native vector charts — bar, horizontal-bar, line, pie, and donut rendered as pure PDF path operators with legends, "nice" axis ticks, and tagged /Figure alt text — each preset a one-click downloadable PDF.
• Authoring+ → The v1.5.0 authoring showcase: SVG <text> labelled charts, the opt-in layout debug overlay plus inspectDocumentLayout(), and typed markup annotations with build + read-back — all in the browser.
• Medical 800-page Web Worker playground → Generate a synthetic 800-page clinical report off the main thread using a Web Worker. Live progress, streaming output, optional Tagged PDF.
• CLI command builder → Compose pdfnative-cli commands (render / sign / inspect / verify / merge / split / extract / annotate / govern / batch / schema) interactively — with --watch, --template, --outline, --font math, ECDSA-SHA256, PAdES-T detection, and one-click presets.
• MCP tool explorer → Browse the pdfnative-mcp toolset (19 tools), copy a ready-to-paste config snippet for Claude / Cursor / Continue / Zed, and generate the same PDFs an AI assistant would receive — all in your browser.
• React renderer → Write JSX in the browser and render a real PDF on-device via pdfnative-react — components compile to pdfnative blocks with no SaaS round-trip. Loaded from a CDN for the demo; the published package stays zero-dependency at its core.

Contributing

Found a typo, an unclear paragraph, or a missing topic? Edit the underlying .md file directly on GitHub and open a pull request. See CONTRIBUTING.md for branch naming conventions (docs/*).