Documentation Guides

New to pdfnative? These guides are the reference shelf. For a guided path that builds up one concept at a time, start with Learn pdfnative — eight steps, about thirty minutes.

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 npm run docs:serve then open localhost:5000/guides/.

• Onboarding → 90-second start for the full ecosystem — the library, pdfnative-cli, pdfnative-mcp, and pdfnative-react. Install + first call for each.
• Choosing your surface → Library, CLI, MCP or React? The decision tree in prose plus a verified capability × surface matrix — every export, command and tool name checked against the sources, with an honest em-dash where a surface lacks a capability. Machine-readable twin in docs/data/surfaces.json.
• Ecosystem use cases → Four production architectures with diagrams, each built from shipped APIs — store the DocSpec JSON instead of the PDF and render on the reader's device, air-gapped PAdES B-LTA archiving (ltv collect → transfer → offline embed), a CI document-regression gate on pdfnative compare exit codes, and edge-rendered PDFs with real HTTP caching (etag/cacheControl).
• 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, incl. extending a local MCP install in place), 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 — validated against the veraPDF reference validator in CI on every commit. v1.7.0 adds declaration guards: strict, onDiagnostic, and the PDFA_* diagnostic codes for configurations that would break the claimed level.
• Print production → Bleed, trim, art & crop boxes, crop and registration marks, /Trapped, duplex print defaults, custom OutputIntent ICC, large-format /UserUnit — print-ready PDFs with zero dependencies.
• Digital signatures → CMS/PKCS#7 detached signatures — RSA SHA-256/384/512 + ECDSA P-256, one-call addSignaturePlaceholder() workflow, Adobe Reader / openssl-cms validation. v1.7.0 adds the PAdES baseline profile (profile: 'pades'), multiple signatures (allowMultiple + fieldName), listSignatures(), and the LTV ladder to B-LTA.
• Long-term validation (LTV) → PAdES B-B → B-LTA — RFC 3161 signature timestamps, /DSS + /VRI validation material, document timestamps, injected providers (zero network in the engine).
• 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 (plus v1.4.0 sweep gradients and blend modes) rendered as native PDF Form XObjects. v1.7.0 adds 73 flag & ZWJ sequences (51 flags + 22 ZWJ) resolved as single colour ligature glyphs. 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, and v1.7.0 --sequences flags|zwj|all|none / --sequence-list for flag & ZWJ ligatures.
• 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) → Nine chart kinds rendered as pure PDF path operators — bar, horizontal-bar, line, pie, donut (v1.6.0), plus stacked bars, area, and scatter with a secondary axis, log & time scales, and data labels (charts v2, v1.7.0). Zero dependencies, multi-series, 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.
• Self-verifying generation → The generate → inspect → assert → correct loop as a first-class pattern: plan with inspectDocumentLayout(), then verify the emitted bytes with extractText(), validatePdfUA() and listSignatures() / openPdf() — and the same loop via CLI inspect --check exit codes and the MCP inspect_pdf assertions, ready for CI and agent loops.
• 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 — 28 tools (incl. the PAdES ladder sign_pdf / add_ltv / timestamp_pdf, update_metadata, the read-only inspect_layout preview, page-tree merge_pdfs / split_pdf / extract_pages, markup annotate_pdf, the network-free draft_governance_issue), pdfA flag, multi-script lang, and a signed-document workflow.
• CLI → pdfnative-cli — 21 commands: render, fill, metadata, sign, verify, ltv, doc-timestamp, encrypt, decrypt, inspect, extract-text, compare, merge / split / extract, annotate, govern, batch, doctor, shell completion, and emit JSON Schemas from the terminal. The complete PAdES ladder (B-B → B-LTA) from the shell, stdin/stdout pipelines, constant-memory streaming, PDF/UA & PDF/A checks, 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>/<Chart> on-device to pdfnative blocks. Charts v2, print production, the PDF/A diagnostics channel, HTTP caching on renderToResponse, 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 48 generators producing 242 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.
• Scale playground → Generate 1,000 to 100,000 pages in a Web Worker, streamed without ever joining the PDF binary. Live progress, streaming output, optional Tagged PDF.
• CLI command builder → Compose pdfnative-cli commands interactively — all twenty-one commands, from render and fill to the full PAdES ladder (sign --timestamp / ltv / doc-timestamp), metadata, compare, batch --manifest and govern — with inline validation and one-click presets. The CLI guide is the complete flag reference.
• MCP tool explorer → Browse the pdfnative-mcp toolset (28 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/*).