A comprehensive collection of sample files covering every feature of pdfnative-cli, organized by category. Each category corresponds to a distinct capability of the pdfnative library.
Generated PDFs are not committed. All output goes to
samples/output/which is git-ignored.
New to pdfnative-cli? Follow this path:
- ✅ Run a quick sample:
node samples/run-all.js --category document - ✅ View sample JSON: render/document/01-minimal.json
- ✅ Try a different feature:
node samples/run-all.js --category barcode - ✅ Read the docs: ../docs/KNOWLEDGE_BASE.md
- ✅ Check FAQ: ../docs/KNOWLEDGE_BASE.md#11-frequently-asked-questions
# Prerequisites: pdfnative-cli installed globally
npm install -g pdfnative-cli
# From the repo root — renders all JSON samples to samples/output/
node samples/run-all.jsRun a single sample:
pdfnative render \
--input samples/render/document/01-minimal.json \
--output samples/output/document/01-minimal.pdfWindows (PowerShell):
pdfnative render `
--input samples\render\document\01-minimal.json `
--output samples\output\document\01-minimal.pdfsamples/
├── run-all.js Cross-platform batch renderer (Node.js ≥ 20)
├── render/ JSON payloads for pdfnative render
│ ├── document/ General-purpose documents (06-max-blocks.* = --max-blocks guard, v1.1.0)
│ ├── table/ Table-heavy layouts
│ ├── barcode/ QR codes, Code 128, EAN-13
│ ├── form/ Interactive PDF form fields
│ ├── toc/ Table of contents
│ ├── link/ Hyperlinks
│ ├── watermark/ Draft / confidential watermarks
│ ├── layout/ Custom page sizes and orientations
│ ├── pdfa/ PDF/A archival conformance
│ ├── encryption/ (v0.2.0) AES-128/256 password protection
│ ├── headers-footers/ (v0.2.0) Page templates with placeholders
│ ├── attachments/ (v0.2.0) PDF/A-3 hybrid invoice (XML attachment)
│ ├── multilang/ (v0.2.0) Real Thai + multilingual PDFs; font loader pattern
│ │ ├── 01-thai.json (guide) Font loader registration — how to enable Thai
│ │ ├── 02-japanese.json (guide) Font loader registration — how to enable Japanese
│ │ ├── 03-thai.json Real Thai monthly report (headings, list, table in Thai)
│ │ ├── 03-thai.js Node.js driver: registerFonts(th) → render 03-thai.json
│ │ ├── 04-multilingual.json Real multilingual doc (EN + Thai + Japanese + Arabic + Russian)
│ │ └── 04-multilingual.js Node.js driver: registerFonts(th,ja,ar,ru) → render 04-multilingual.json
│ ├── table-variant/ (v0.2.0) Table-centric PdfParams (--variant table)
│ ├── font/ (v0.3.0) `--font` / `--lang` flag demo (latin preset)
│ │ ├── 01-latin.* Latin preset shortcut
│ │ ├── 02-new-scripts.* (v1.1.0) Six new 1.3.0 scripts + COLRv1 colour emoji
│ │ └── 03-emoji.* (v1.1.0) Monochrome emoji preset (`--font emoji`)
│ ├── template/ (v0.3.0) `--template` deep-merge demo (base + override)
│ ├── watch/ (v0.3.0) `--watch` interactive auto-rebuild demo
│ ├── table-smart/ (v1.0.0) Smart tables: zebra, caption, repeat-header, wrap
│ ├── outline/ (v1.2.0) PDF bookmarks — `--outline auto` + explicit tree
│ ├── math/ (v1.2.0) Math/technical symbols via `--font math`
│ └── inspect-layout/ (v1.2.0) `--inspect-layout` report + `--debug-layout` guides
├── merge/ (v1.2.0) Concatenate PDFs (pdfnative page-tree)
├── split/ (v1.2.0) Split one PDF into many (per-page or per-range)
├── extract/ (v1.2.0) Pull selected pages into a new PDF
├── annotate/ (v1.2.0) Attach markup annotations (incremental save)
├── govern/ (v1.2.0) AI-governance / HITL: rules, policy, verify-issue
├── batch/ (v1.0.0) Parallel directory render (pdfnative batch)
├── agent/ (v1.1.0) Agent-native contract: --json envelope, --dry-run, schema
│ ├── 01-json-and-dry-run.* --json status envelope + --dry-run validation
│ ├── 02-schema.* `schema` command — versioned JSON Schemas
│ ├── 03-error-envelope.* Deterministic failures (stable E_* error codes)
│ └── 04-token-economy.* ~90% smaller output via --summary / --fields / compact JSON
├── completion/ (v1.0.0) Shell-completion script generation
├── config/ (v1.0.0) `.pdfnativerc.json` default-flags demo
├── sign/ Digital signature shell / PowerShell scripts
│ ├── 01-basic.* Self-signed RSA-SHA256 sign
│ ├── 02-with-metadata.* (v0.2.0) Sign with reason / location / signing-time
│ ├── 03-ecdsa.* (v0.3.0) P-256 ECDSA-SHA256 sign
│ ├── 04-roundtrip.* (v0.3.0) render → sign → verify pipeline
│ ├── 05-cert-chain.* (v1.1.0) Root-CA → signer chain via --cert-chain + verify --trust
│ ├── 06-timestamp-reserved.* (v1.1.0) --timestamp is reserved → exit 2 (E_UNSUPPORTED)
│ └── 07-native-crypto.* (v1.2.0) Native node:crypto (default) vs pure-JS (--pure-crypto)
├── inspect/ PDF inspection shell / PowerShell scripts
│ ├── 01-json.* JSON metadata report
│ ├── 02-text.* Human-readable text report
│ ├── 03-verbose-pages.* Per-page detail + verbose trailer/catalog keys
│ ├── 04-check-pdfa.* CI gate: assert PDF/A conformance
│ ├── 05-pdfua.* (v1.1.0) PDF/UA (ISO 14289-1) structural validation gate
│ ├── 06-check-signed-encrypted.* (v1.1.0) CI gates for --check signed / --check encrypted
│ └── 07-annotations.* (v1.2.0) List markup + link annotations (inspect --annotations)
├── verify/ Signature verification shell / PowerShell scripts
│ ├── 01-self-signed.* (v0.2.0) Verify a self-signed PDF
│ ├── 02-strict-mode.* (v0.2.0) `--strict` exits non-zero on failure
│ ├── 03-cms-rsa.* (v0.3.0) Verify CMS RSA-SHA256 signature value
│ ├── 04-cms-ecdsa.* (v0.3.0) Verify CMS ECDSA-SHA256 signature value
│ ├── 05-revocation.* (v1.0.0) OCSP/CRL revocation + timestamp (PAdES-T)
│ └── 06-online-revocation.* (v1.1.0) Offline default + commented SSRF-guarded online variant
└── streaming/ Streaming render Node.js scripts
| File | Description |
|---|---|
| 01-minimal.json | Bare-minimum document: a single heading and paragraph |
| 02-report.json | Business report with metadata, headers/footers, mixed blocks |
| 03-all-blocks.json | Reference — every block type in one document (heading, paragraph, list, table, barcode, link, form fields, page break, spacer) |
| 04-invoice.json | Invoice with line-item table, totals, and company branding |
| 05-technical-spec.json | Technical specification with multi-level headings and code-style paragraphs |
| 06-max-blocks.json | (v1.1.0) Document body for the --max-blocks large-report guard demo |
| 06-max-blocks.sh | (v1.1.0) Render with a generous --max-blocks 10000, then trip the guard with --max-blocks 3 |
| 06-max-blocks.ps1 | (v1.1.0) PowerShell equivalent |
| File | Description |
|---|---|
| 01-project-status.json | Project status table with milestone tracking |
| 02-financial-summary.json | Financial summary with revenue, cost, and margin rows |
| File | Description |
|---|---|
| 01-qr-url.json | QR code linking to a URL (format: "qr") |
| 02-code128-shipping.json | Code 128 barcode for a shipping label (format: "code128") |
| 03-ean13-product.json | EAN-13 product barcode (format: "ean13") |
| File | Description |
|---|---|
| 01-contact-form.json | Contact form: text, email, phone, textarea fields |
| 02-survey.json | Survey with radio, checkbox, and select fields |
| File | Description |
|---|---|
| 01-document-with-toc.json | Multi-section document with auto-generated TOC block |
| File | Description |
|---|---|
| 01-resource-directory.json | Resource directory page with inline hyperlinks |
| File | Description |
|---|---|
| 01-draft.json | Document with DRAFT status indicator (heading + footer) |
| 02-confidential.json | Document with CONFIDENTIAL status indicator (heading + footer) |
| 03-cli-flags.json | (v1.1.0) Document body for the CLI watermark-flag demo |
| 03-cli-flags.sh | (v1.1.0) Overlay a real watermark via --watermark-text/-opacity/-angle/-color/-font-size/-position |
| 03-cli-flags.ps1 | (v1.1.0) PowerShell equivalent |
Note: Visual watermark overlays are exposed through the CLI via the --watermark-text / --watermark-image flags (plus --watermark-opacity, --watermark-angle, --watermark-color, --watermark-font-size, --watermark-position) — see 03-cli-flags.*. The 01/02 samples instead show the heading/footer-text approach for status indication. Watermarks can also be set programmatically:
import { buildDocumentPDFBytes } from 'pdfnative';
const pdf = buildDocumentPDFBytes(params, {
watermark: { text: { text: 'DRAFT', opacity: 0.15, angle: 45 } }
});| File | Description |
|---|---|
| 01-us-letter.json | US Letter (612 × 792 pt) — default US paper format |
| 02-a5-portrait.json | A5 portrait (419.53 × 595.28 pt) — compact booklet size |
| 03-landscape-a4.json | A4 landscape (841.89 × 595.28 pt) — wide-format reports |
| File | Conformance | Standard |
|---|---|---|
| 01-pdfa-1b.json | PDF/A-1b | ISO 19005-1 — baseline archival |
| 02-pdfa-2b.json | PDF/A-2b | ISO 19005-2 — transparency, JPEG 2000 |
| 03-pdfa-3b.json | PDF/A-3b | ISO 19005-3 — embedded file attachments |
| 04-pdfa-2u.json | PDF/A-2u | ISO 19005-2 — every glyph mapped to Unicode |
PDF/A conformance can also be set from the CLI via the --tagged flag (or the deprecated --conformance alias) instead of the JSON layout.tagged field:
# Preferred (v0.2.0+)
pdfnative render --input doc.json --output doc.pdf --tagged pdfa2b
# Deprecated alias — still works, prints a stderr deprecation notice
pdfnative render --input doc.json --output doc.pdf --conformance 2b| File | Description |
|---|---|
| 01-aes128-protected.json | Document body for an AES-128 encrypted PDF |
| 01-aes128-protected.sh | Bash driver — sets $PDFNATIVE_ENCRYPT_OWNER_PASS / $PDFNATIVE_ENCRYPT_USER_PASS and calls --encrypt-algorithm aes128 --encrypt-permissions print |
| 01-aes128-protected.ps1 | PowerShell equivalent |
| 02-aes256-protected.json | (v1.1.0) Document body for an AES-256 encrypted PDF |
| 02-aes256-protected.sh | (v1.1.0) Bash driver — --encrypt-algorithm aes256 --encrypt-permissions print |
| 02-aes256-protected.ps1 | (v1.1.0) PowerShell equivalent |
Security: owner / user passwords are read from environment variables first, then --encrypt-owner-pass / --encrypt-user-pass flags. Encryption is mutually exclusive with --tagged pdfa* (ISO 19005 forbids encrypted PDF/A).
| File | Description |
|---|---|
| 01-page-numbers.json | Multi-page document body |
| 01-page-numbers.sh | Demonstrates --header-left/-center/-right and --footer-* with {page}, {pages}, {date}, {title} placeholders |
| 01-page-numbers.ps1 | PowerShell equivalent |
Note: the {pages} placeholder requires multi-pass pagination; it is rejected when combined with --stream.
| File | Description |
|---|---|
| 01-pdfa3-with-xml.json | PDF/A-3b invoice body |
| invoice.xml | Structured payload to embed |
| 01-pdfa3-with-xml.sh | Renders with --tagged pdfa3b --attachment <path>:<mime>:<rel>:<desc> |
| 01-pdfa3-with-xml.ps1 | PowerShell equivalent |
This is the Factur-X / ZUGFeRD pattern — a human-readable PDF/A-3 with a machine-readable XML attachment.
pdfnative ships Noto Sans font data for 16 scripts inside the package itself
(pdfnative/dist/../fonts/noto-*-data.js). No external font files, no network
access, no extra dependencies. Font data is loaded lazily on first use and cached.
Because the pdfnative CLI starts a fresh process per invocation, font loaders must
be registered via registerFonts() before the render call — which is only
possible from a programmatic Node.js context. The two .js driver scripts below
do exactly that and then call buildDocumentPDFBytes directly.
| File | Description |
|---|---|
| 01-thai.json | Guide: how to enable Thai rendering via registerFonts({ th: () => import(...) }) |
| 02-japanese.json | Guide: how to enable Japanese / CJK rendering |
| 03-thai.json | Real Thai document — monthly report with headings, paragraphs, list, table (all in Thai) |
| 04-multilingual.json | Real multilingual document — English + Thai + Japanese + Arabic (RTL) + Russian in one PDF |
| File | Description |
|---|---|
| 03-thai.js | Registers Noto Thai → renders 03-thai.json → output/multilang/03-thai.pdf |
| 04-multilingual.js | Registers Thai + Japanese + Arabic + Russian → renders 04-multilingual.json → output/multilang/04-multilingual.pdf |
| 01-thai.sh | Bash: runs 03-thai.js then 04-multilingual.js |
| 01-thai.ps1 | PowerShell equivalent |
# Run Thai sample only
node samples/render/multilang/03-thai.js
# Run multilingual sample (Thai + Japanese + Arabic + Russian)
node samples/render/multilang/04-multilingual.js
# Run both via the shell script
bash samples/render/multilang/01-thai.shFont loader pattern (how it works):
import { registerFonts, loadFontData, buildDocumentPDFBytes } from 'pdfnative';
import { dirname, join } from 'node:path';
import { fileURLToPath, pathToFileURL } from 'node:url';
// Resolve pdfnative's bundled fonts directory (works with any package manager)
const fontsDir = join(dirname(fileURLToPath(import.meta.resolve('pdfnative'))), '..', 'fonts');
const fontUrl = (name) => pathToFileURL(join(fontsDir, name)).href;
// Register loaders (lazy — fonts are not loaded until first use)
registerFonts({
th: () => import(fontUrl('noto-thai-data.js')), // Thai
ja: () => import(fontUrl('noto-jp-data.js')), // Japanese
ar: () => import(fontUrl('noto-arabic-data.js')), // Arabic (RTL)
ru: () => import(fontUrl('noto-cyrillic-data.js')), // Russian
});
// Load font data (async, cached after first call)
const thFont = await loadFontData('th');
// Inject into DocumentParams
const pdf = buildDocumentPDFBytes({
blocks: [{ type: 'paragraph', text: 'สวัสดีครับ Hello!' }],
fontEntries: thFont ? [{ fontData: thFont, fontRef: '/F3', lang: 'th' }] : [],
});Supported font packages (all bundled with pdfnative ≥ 1.0.5):
| Language | Code | Font package |
|---|---|---|
| Thai | th |
noto-thai-data.js |
| Japanese | ja |
noto-jp-data.js |
| Chinese Simplified | zh |
noto-sc-data.js |
| Korean | ko |
noto-kr-data.js |
| Arabic | ar |
noto-arabic-data.js |
| Russian / Cyrillic | ru |
noto-cyrillic-data.js |
| Hindi / Devanagari | hi |
noto-devanagari-data.js |
| Hebrew | he |
noto-hebrew-data.js |
| Greek | el |
noto-greek-data.js |
| Turkish | tr |
noto-turkish-data.js |
| Vietnamese | vi |
noto-vietnamese-data.js |
| Polish | pl |
noto-polish-data.js |
| Bengali | bn |
noto-bengali-data.js |
| Tamil | ta |
noto-tamil-data.js |
| Georgian | ka |
noto-georgian-data.js |
| Armenian | hy |
noto-armenian-data.js |
| File | Description |
|---|---|
| 01-financial-transactions.json | PdfParams payload — title, infoItems, headers, rows, balanceText, countText, footerText |
| 01-financial-transactions.sh | Driver using --variant table |
| 01-financial-transactions.ps1 | PowerShell equivalent |
--variant table switches the renderer to buildPDFBytes / buildPDFStream, which accept the lower-level PdfParams shape (suitable for ledger / transactional reports).
| File | Description |
|---|---|
| 01-latin.json | Plain Latin-1 document body |
| 01-latin.sh | Renders with --font latin --lang latin |
| 01-latin.ps1 | PowerShell equivalent |
| 02-new-scripts.json | (v1.1.0) Six 1.3.0 scripts (Telugu, Sinhala, Khmer, Burmese, Tibetan, Amharic) + COLRv1 colour emoji |
| 02-new-scripts.sh | (v1.1.0) Renders the new scripts with per-script --font/--lang flags |
| 02-new-scripts.ps1 | (v1.1.0) PowerShell equivalent |
| 03-emoji.json | (v1.1.0) Monochrome emoji document body |
| 03-emoji.sh | (v1.1.0) Renders with --font emoji --lang emoji |
| 03-emoji.ps1 | (v1.1.0) PowerShell equivalent |
The --font and --lang flags select a preset (or, repeated, multiple scripts) from pdfnative's bundled font registry without requiring a registerFonts driver script. latin is the safe baseline; non-Latin presets can be selected directly by code (te, si, km, my, bo, am, emoji, color-emoji, …).
| File | Description |
|---|---|
| base.json | Reusable base — common metadata, headers/footers |
| override.json | Document-specific blocks; merged on top of the base |
| 01-merge.sh | pdfnative render --template base.json --input override.json --output … |
| 01-merge.ps1 | PowerShell equivalent |
The CLI deep-merges --template into --input before rendering. Use this to share boilerplate across many documents (e.g. corporate header/footer templates). This category is skipped by run-all.js because both files are partial payloads.
| File | Description |
|---|---|
| 01-basic.sh | Starts pdfnative render … --watch and re-renders on JSON change (Bash) |
| 01-basic.ps1 | PowerShell equivalent |
--watch keeps the process running and rebuilds the PDF whenever the input JSON changes. Skipped by run-all.js because it never exits — run manually and Ctrl-C when done.
| File | Description |
|---|---|
| 01-smart-invoice.json | Invoice using pdfnative 1.2.0 smart-table fields set directly in JSON: zebra, caption, repeatHeader, wrap, minRowHeight, cellPadding |
| 01-smart-invoice.sh | Renders the smart-table invoice (Bash) |
| 01-smart-invoice.ps1 | PowerShell equivalent |
Smart-table fields live on the table block in the JSON payload (no extra CLI flags required), so run-all.js renders this category automatically. Document-wide defaults can also be supplied via the --table-wrap and --zebra render flags.
| File | Description |
|---|---|
| 01-headings.json | Multi-section document used for both bookmark demos |
| 02-outline-tree.json | Explicit OutlineItem[] tree (nested, bold, coloured, collapsed) |
| 01-outline.sh | Renders bookmarks two ways: --outline auto (from headings) and --outline <tree.json> |
| 01-outline.ps1 | PowerShell equivalent |
--outline auto derives the bookmark tree from the document's headings; --outline <file.json> supplies an explicit tree. run-all.js renders 01-headings.json with --outline auto and skips the non-document 02-outline-tree.json.
| File | Description |
|---|---|
| 01-math.json | Identities using operators, Greek letters, set relations, blackboard-bold |
| 01-math.sh | Renders with the bundled math font (--font math) registered alongside Latin |
| 01-math.ps1 | PowerShell equivalent |
Registering --font math lets pdfnative auto-route math/technical code points to the Noto Sans Math font instead of rendering .notdef tofu.
| File | Description |
|---|---|
| 01-inspect-layout.sh | --inspect-layout emits a LayoutInspection JSON report; --debug-layout overlays margin/content/cell guides on a PDF |
| 01-inspect-layout.ps1 | PowerShell equivalent |
--inspect-layout replaces the PDF output with a JSON report describing every page's blocks, positions and sizes — ideal for regression-testing layout. --debug-layout [margins,content,cells] instead renders a normal PDF with visual guides overlaid.
pdfnative 1.5.0's page-tree API powers three composable document operations. Each ships Bash + PowerShell drivers that render their inputs first, then transform them.
| File | Description |
|---|---|
| 01-merge.sh | Renders three documents, then merges them into one PDF (sources as positional args) |
| 01-merge.ps1 | PowerShell equivalent |
| File | Description |
|---|---|
| multipage.json | Four-page source document |
| 01-split.sh | Splits per-page (default) and per-range (--pages 1-2,3-4) |
| 01-split.ps1 | PowerShell equivalent |
| File | Description |
|---|---|
| 01-extract.sh | Extracts pages in arbitrary order (--pages 4,1-2; order preserved, repeats allowed) |
| 01-extract.ps1 | PowerShell equivalent |
| File | Description |
|---|---|
| 01-annotations.json | Three markup annotations (highlight, sticky text note, review square) on page 1 |
| 01-annotate.sh | Attaches the annotations with an incremental save (original bytes preserved) |
| 01-annotate.ps1 | PowerShell equivalent |
Annotations are attached with an incremental save, so any existing signature stays intact. Read them back with inspect --annotations.
| File | Description |
|---|---|
| draft-good.md | A compliant issue draft (repro block + environment; no runtime dependency) |
| draft-bad.md | A non-compliant draft (proposes npm install …, no repro) |
| 01-rules.sh | Prints the human/agent protocol (govern rules) and machine policy (govern policy) |
| 01-rules.ps1 | PowerShell equivalent |
| 02-verify-issue.sh | Gates a draft: PASS (exit 0) for the compliant one, BLOCK (exit 1, E_POLICY) for the bad one |
| 02-verify-issue.ps1 | PowerShell equivalent |
Agents act as draftsmen: govern verify-issue is a local pre-flight, but a human must always review and submit under their own GitHub identity. Nothing here touches the network.
Demonstrate the pdfnative sign command. Both Unix shell and PowerShell scripts are provided.
| Script | Description |
|---|---|
| sign/01-basic.sh | Render a PDF, generate a self-signed certificate, then sign it (Bash) |
| sign/01-basic.ps1 | Same workflow for Windows PowerShell |
| sign/02-with-metadata.sh | (v0.2.0) Sign with --reason, --name, --location, --contact, --signing-time (Bash) |
| sign/02-with-metadata.ps1 | (v0.2.0) PowerShell equivalent |
| sign/03-ecdsa.sh | (v0.3.0) Generate a P-256 keypair and sign with --algorithm ecdsa-sha256 (Bash) |
| sign/03-ecdsa.ps1 | (v0.3.0) PowerShell equivalent |
| sign/04-roundtrip.sh | (v0.3.0) Full render → sign → verify pipeline; asserts signatureValid: true via jq |
| sign/04-roundtrip.ps1 | (v0.3.0) PowerShell equivalent |
| sign/05-cert-chain.sh | (v1.1.0) Build a root-CA → signer chain, sign with --cert-chain, then verify --trust <root> |
| sign/05-cert-chain.ps1 | (v1.1.0) PowerShell equivalent |
| sign/06-timestamp-reserved.sh | (v1.1.0) Shows --timestamp is reserved and exits 2 (E_UNSUPPORTED) — sign-side LTV is upstream-blocked |
| sign/06-timestamp-reserved.ps1 | (v1.1.0) PowerShell equivalent |
| sign/07-native-crypto.sh | (v1.2.0) Signs the same PDF with native node:crypto (default) and pure-JS (--pure-crypto), verifying both |
| sign/07-native-crypto.ps1 | (v1.2.0) PowerShell equivalent |
Prerequisites: openssl on your PATH (ships with Git for Windows).
Security note: The generated key/certificate in samples/output/sign/keys/ is for demonstration only. Never use a demo certificate in production.
Using environment variables for key material (recommended for CI):
PDFNATIVE_SIGN_KEY="$(cat signing.key)" \
PDFNATIVE_SIGN_CERT="$(cat signing.crt)" \
pdfnative sign --input unsigned.pdf --output signed.pdfDemonstrate the pdfnative inspect command.
| Script | Description |
|---|---|
| inspect/01-json.sh | Inspect a PDF and write a JSON metadata report (Bash) |
| inspect/01-json.ps1 | Same for Windows PowerShell |
| inspect/02-text.sh | Inspect a PDF/A document, print human-readable text to stdout (Bash) |
| inspect/02-text.ps1 | Same for Windows PowerShell |
| inspect/03-verbose-pages.sh | (v0.2.0) --verbose + --pages deep inspection report |
| inspect/03-verbose-pages.ps1 | (v0.2.0) PowerShell equivalent |
| inspect/04-check-pdfa.sh | (v0.2.0) Assert PDF/A conformance via --check pdfa (CI-friendly exit code) |
| inspect/04-check-pdfa.ps1 | (v0.2.0) PowerShell equivalent |
| inspect/05-pdfua.sh | (v1.1.0) PDF/UA (ISO 14289-1) structural validation gate via --check pdfua |
| inspect/05-pdfua.ps1 | (v1.1.0) PowerShell equivalent |
| inspect/06-check-signed-encrypted.sh | (v1.1.0) CI gates for --check encrypted (PASS) and --check signed (FAIL on unsigned) |
| inspect/06-check-signed-encrypted.ps1 | (v1.1.0) PowerShell equivalent |
| inspect/07-annotations.sh | (v1.2.0) Render → annotate → inspect --annotations to list markup + link annotations |
| inspect/07-annotations.ps1 | (v1.2.0) PowerShell equivalent |
Demonstrate the pdfnative verify command — verifies CMS/PKCS#7 signatures embedded in a PDF (integrity, certificate chain, trust evaluation, and CMS signature-value verification).
| Script | Description |
|---|---|
| verify/01-self-signed.sh | Verify a PDF signed with a self-signed certificate (Bash) |
| verify/01-self-signed.ps1 | PowerShell equivalent |
| verify/02-strict-mode.sh | --strict mode — exits non-zero if any signature fails (CI-friendly) |
| verify/02-strict-mode.ps1 | PowerShell equivalent |
| verify/03-cms-rsa.sh | (v0.3.0) Verify CMS RSA-SHA256 signature value end-to-end |
| verify/03-cms-rsa.ps1 | (v0.3.0) PowerShell equivalent |
| verify/04-cms-ecdsa.sh | (v0.3.0) Verify CMS ECDSA-SHA256 (P-256) signature value end-to-end |
| verify/04-cms-ecdsa.ps1 | (v0.3.0) PowerShell equivalent |
| verify/05-revocation.sh | (v1.0.0) Revocation checking — --revocation offline|online + --revocation-policy strict|soft-fail (OCSP/CRL + PAdES-T timestamp) |
| verify/05-revocation.ps1 | (v1.0.0) PowerShell equivalent |
| verify/06-online-revocation.sh | (v1.1.0) Offline-by-default verify, with a commented SSRF-guarded --revocation online variant |
| verify/06-online-revocation.ps1 | (v1.1.0) PowerShell equivalent |
Scope (v1.0.0): verify checks integrity (byte-range SHA-256), CMS signature value (RSA-PKCS#1 v1.5 SHA-256 and ECDSA-SHA256 over P-256), certificate chain signatures, trust (against --trust <root.pem> PEM roots, or self-signed acceptance), RFC 3161 timestamp validation (PAdES-T), and OCSP (RFC 6960) + CRL (RFC 5280) revocation — embedded from the PDF /DSS offline by default, with opt-in SSRF-guarded online fetching via --revocation online. Sign-side LTV (embedding timestamps/DSS at signing time) is upstream-blocked in pdfnative — see ROADMAP.md and SECURITY.md.
Demonstrate the pdfnative batch command — renders every *.json in a directory to <output-dir>/<name>.pdf in parallel, reusing the full render pipeline. Exits non-zero if any file fails.
| Script | Description |
|---|---|
| batch/01-batch.sh | Batch-render render/document/*.json with --concurrency 4 --compress (Bash) |
| batch/01-batch.ps1 | PowerShell equivalent |
| batch/02-fail-fast.sh | (v1.1.0) --fail-fast aborts on the first failure (one valid + one invalid input); asserts non-zero exit |
| batch/02-fail-fast.ps1 | (v1.1.0) PowerShell equivalent |
Render flags other than --input-dir / --output-dir / --concurrency / --fail-fast / --format are forwarded to every file.
Demonstrate the pdfnative completion command — emits shell-completion scripts for bash, zsh, and fish.
| Script | Description |
|---|---|
| completion/01-generate.sh | Prints install one-liners for each shell, then previews the bash script (Bash) |
| completion/01-generate.ps1 | PowerShell equivalent |
# bash (system-wide)
pdfnative completion bash | sudo tee /etc/bash_completion.d/pdfnative >/dev/null
# zsh (first fpath entry)
pdfnative completion zsh > "${fpath[1]}/_pdfnative"
# fish
pdfnative completion fish > ~/.config/fish/completions/pdfnative.fishDemonstrate .pdfnativerc.json — a config file discovered cwd-upward that supplies default flags. Top-level keys are global defaults; keys named after a command (render, verify, batch, …) are per-command sections. Precedence is CLI flags > env > config.
| File | Description |
|---|---|
| config/.pdfnativerc.json | Sample config: letter page size + compression + zebra tables for render, offline soft-fail revocation for verify, concurrency 8 for batch |
| config/01-config.sh | Renders from the config dir (defaults apply) vs --no-config (built-in defaults) (Bash) |
| config/01-config.ps1 | PowerShell equivalent |
Use --config <path> to point at an explicit config file, or --no-config to ignore config discovery entirely.
Demonstrates piping a large JSON payload directly to pdfnative render --stream, writing the PDF to disk without buffering the whole document in Node.js.
| Script | Description |
|---|---|
| streaming/01-large-document.js | Generates a 200-section document via the --stream render path |
| streaming/02-page-by-page.sh | (v1.0.0) --stream-page-by-page — emit one page at a time (bounded memory; no TOC) |
| streaming/02-page-by-page.ps1 | PowerShell equivalent |
| streaming/03-true-streaming.sh | (v1.1.0) --stream-true — fully incremental streaming render |
| streaming/03-true-streaming.ps1 | PowerShell equivalent |
node samples/streaming/01-large-document.js
bash samples/streaming/02-page-by-page.sh
bash samples/streaming/03-true-streaming.shnode samples/run-all.js [--category <name>] [--clean]
--category <name> Only render samples in render/<name>/
e.g. --category barcode
--clean Delete samples/output/ before running
Skipped categories: watch/ and template/ are skipped by default — watch/ runs forever, and template/ contains partial payloads that must be merged via --template. Run them manually using the per-script .sh / .ps1 drivers.
Examples:
# Render only barcode samples
node samples/run-all.js --category barcode
# Render the v0.3.0 font preset sample
node samples/run-all.js --category font
# Run the full render → sign → verify pipeline
bash samples/sign/04-roundtrip.sh
# Clean output and re-render everything
node samples/run-all.js --clean{
"scripts": {
"build:pdf": "pdfnative render --input data/document.json --output dist/report.pdf",
"build:pdf:archive": "pdfnative render --input data/document.json --output dist/report.pdf --conformance pdfa2b"
}
}- name: Render PDF
run: pdfnative render --input docs/spec.json --output dist/spec.pdf
- name: Sign PDF
env:
PDFNATIVE_SIGN_KEY: ${{ secrets.SIGN_KEY }}
PDFNATIVE_SIGN_CERT: ${{ secrets.SIGN_CERT }}
run: pdfnative sign --input dist/spec.pdf --output dist/spec-signed.pdf
- name: Upload artifact
uses: actions/upload-artifact@v4
with:
name: signed-pdf
path: dist/spec-signed.pdfFROM node:22-alpine
RUN npm install --global pdfnative-cli
WORKDIR /work
COPY document.json .
RUN pdfnative render --input document.json --output output.pdfimport { spawn } from 'node:child_process';
function renderToFile(params: object, outputPath: string): Promise<void> {
return new Promise((resolve, reject) => {
const child = spawn('pdfnative', ['render', '--output', outputPath], {
stdio: ['pipe', 'ignore', 'inherit'],
});
child.stdin.end(JSON.stringify(params), 'utf8');
child.on('close', (code) => {
code === 0 ? resolve() : reject(new Error(`Exit code ${code}`));
});
});
}
await renderToFile(
{ title: 'Invoice', blocks: [{ type: 'paragraph', text: 'Amount due: $100' }] },
'invoice.pdf',
);Every block type accepted by pdfnative render is demonstrated in render/document/03-all-blocks.json.
| Block type | Key fields | Sample |
|---|---|---|
heading |
text, level (1–6) |
03-all-blocks.json |
paragraph |
text, align, fontSize |
02-report.json |
table |
headers[], rows[][] |
01-project-status.json |
list |
style (bullet|numbered), items[] |
03-all-blocks.json |
barcode |
format, data, width |
01-qr-url.json |
link |
text, url |
01-resource-directory.json |
toc |
title, maxLevel |
01-document-with-toc.json |
formField |
fieldType, name, label, value |
01-contact-form.json |
spacer |
height |
any document sample |
pageBreak |
(no fields) | 03-all-blocks.json |
ImageBlockandSvgBlockrequire binary data (Uint8Array) and cannot be expressed in plain JSON. Use thepdfnativeNode.js API directly for those block types.
- ../README.md — Installation, quick start, command reference
- ../docs/KNOWLEDGE_BASE.md — Full CLI documentation, architecture, FAQ
- pdfnative library — Core PDF generation engine (Node.js API with more features)