Cookbook: Technical User Manual

Generate a structured technical documentation PDF with compliance tables, installation steps, configuration references, and a deployment checklist using renderTemplate().

Quick start

import { createDocument, rgb } from "@barrierbreak/a11ydocs-pdf";

async function ttf(url: string): Promise<Uint8Array> {
  return new Uint8Array(await (await fetch(url)).arrayBuffer());
}

const cdn = "https://cdn.jsdelivr.net/npm/@expo-google-fonts";
const FONTS = {
  inter400: `${cdn}/inter/400Regular/Inter_400Regular.ttf`,
  inter700: `${cdn}/inter/700Bold/Inter_700Bold.ttf`,
};

const doc = createDocument({
  language: "en-US",
  conformance: "pdfua-1",
  tagged: true,
  structureRoot: "Document",
  title: "A11yDocs PDF Engine Integration Guide",
  info: { author: "Accessibility Engineering Division" },
  defaults: { fontSize: 11, color: rgb(0.1, 0.1, 0.15) },
});

const [inter400, inter700] = await Promise.all([
  ttf(FONTS.inter400),
  ttf(FONTS.inter700),
]);

doc.registerFontFamily("Inter", { regular: inter400, bold: inter700 });

Unlike the invoice and bank statement cookbooks, this template has no logo and no encryption — it is a plain documentation PDF with no asset dependencies beyond the two font files.

Color palette

const BRAND = rgb(0.05, 0.25, 0.55);
const MUTED = rgb(0.45, 0.45, 0.5);
const TABLE_BORDER = rgb(0.72, 0.76, 0.82);
const TABLE_HEADER = rgb(0.92, 0.94, 0.98);

Building the manual

Document title and version line

An h1 block sets the document title. A paragraph with class: "muted" renders the version and compliance metadata line in a smaller, greyed-out style:

{ type: "heading", text: "barrierbreak/a11ydocs-pdf User Manual", options: { level: 1 } },
{
  type: "paragraph",
  text: "Version: 1.7.0  |  Target Framework: Node.js / TypeScript  |  Compliance: PDF/UA-1 & WCAG 2.2",
  class: "muted",
},

The class property references a named style defined in the styles block, allowing font size, color, and line height to be controlled from one place.

Vertical label-value tables

The environmental compliance table uses headerColumns: 1 with scope: "row" on each label cell. This is the same vertical layout pattern as the bank statement's account details and the joining letter's appointment details — appropriate whenever rows are independent facts rather than records in a shared column schema:

{
  type: "table",
  rows: [
    [{ text: "System Profile Requirement", header: true, bold: true, scope: "row" }, { text: "Minimum Operational Standard"                              }],
    [{ text: "Node.js Environment",        header: true, bold: true, scope: "row" }, { text: "v18.12.0 LTS or superior runtime engine"                  }],
    [{ text: "Font Embedding Engine",      header: true, bold: true, scope: "row" }, { text: "TrueType (.ttf) or OpenType (.otf) with full Unicode maps" }],
    [{ text: "Metadata Engine",            header: true, bold: true, scope: "row" }, { text: "XMP (Extensible Metadata Platform) schema injection reader"}],
  ],
  options: {
    headerColumns: 1,
    borders: "all",
    borderColor: TABLE_BORDER,
    headerBackground: TABLE_HEADER,
  },
},

Step-numbered installation table

The installation table uses both headerRows: 1 (Phase / Command column headers) and headerColumns: 1 with scope: "row" on the step labels, so each command cell is associated with both its column header and its step number:

{
  type: "table",
  rows: [
    [
      { text: "Phase",                              header: true, bold: true },
      { text: "Terminal CLI Command Execution String", header: true, bold: true },
    ],
    [{ text: "Step 1", header: true, scope: "row" }, "npm config set @barrierbreak:registry=https://npm.barrierbreak.net"],
    [{ text: "Step 2", header: true, scope: "row" }, "npm install @barrierbreak/a11ydocs-pdf"],
  ],
  options: {
    headerRows: 1,
    headerColumns: 1,
    borders: "all",
    borderColor: TABLE_BORDER,
    headerBackground: TABLE_HEADER,
  },
},

Plain strings (rather than cell objects) are valid for data cells that need no special styling.

Three-column reference tables

The configuration options table and the tabular component schema both use headerRows: 1 with scope: "row" on the first column. This pattern suits any reference table where each row is an independent entry and the first column names that entry:

{
  type: "table",
  rows: [
    [
      { text: "Configuration Option",     header: true, bold: true },
      { text: "Value Variable Input",     header: true, bold: true },
      { text: "A11y Screen Reader Purpose", header: true, bold: true },
    ],
    [{ text: "language",      header: true, scope: "row" }, { text: "en-US"       }, { text: "Forces correct pronunciation synthesizer engine activation"          }],
    [{ text: "structureRoot", header: true, scope: "row" }, { text: '"Document"'  }, { text: "Initializes the primary parent tree tag structural layer"            }],
    [{ text: "tagged",        header: true, scope: "row" }, { text: "true"        }, { text: "Enables explicit reading order flow boundaries throughout parsing"   }],
  ],
  options: {
    headerRows: 1,
    borders: "all",
    borderColor: TABLE_BORDER,
    headerBackground: TABLE_HEADER,
  },
},

Page break

A pageBreak block separates the installation and configuration sections from the structural component mappings, keeping the two conceptual halves of the manual on separate pages:

{ type: "pageBreak" },

Level-3 headings for subsections

Section 4 introduces a level-3 heading for its subsection. The styles block defines heading3 separately so it can carry a distinct font size while still inheriting the brand color:

{ type: "heading", text: "4. Accessible Structural Component Mappings", options: { level: 2 } },
{ type: "heading", text: "4.1 Tabular Component Configuration Schema",  options: { level: 3 } },

Heading levels must not skip — a level: 3 heading must always follow a level: 2 heading in the same section.

Deployment checklist

The PDF/UA deployment checklist uses a list block. Each item is a short rule the integrator must verify before shipping:

{
  type: "list",
  items: [
    { body: "Always use explicit layout tag rules on your footers ('Artifact' or 'P') to prevent reading sequence disruption." },
    { body: "Provide alternative descriptive strings explicitly whenever rendering visual chart files or svg layout structures." },
    { body: "Maintain logical structural level indexing pipelines consistently (e.g., skip from Level 1 straight down to Level 3 is prohibited)." },
    { body: "Verify output binaries using validation automation engines like PAC3 or Adobe Accessibility Checker prior to deployment." },
  ],
},

Full template

doc.renderTemplate({
  autoOutline: { maxLevel: 6 },

  page: {
    size: "A4",
    margin: 48,
    font: "Inter",
    spacing: {
      paragraphAfter: 5,
      headingBefore: { 2: 18, 3: 12 },
      headingAfter: { 1: 4, 2: 8, 3: 6 },
      tableBefore: 6,
      tableAfter: 14,
    },
  },

  styles: {
    heading1: { fontSize: 22, color: BRAND },
    heading2: { fontSize: 16, color: BRAND },
    heading3: { fontSize: 12, color: BRAND },
    paragraph: { fontSize: 10, lineHeight: 15 },
    muted: { fontSize: 9, color: MUTED, lineHeight: 14 },
  },

  blocks: [
    // ── Title ────────────────────────────────────────────
    {
      type: "heading",
      text: "barrierbreak/a11ydocs-pdf User Manual",
      options: { level: 1 },
    },
    {
      type: "paragraph",
      text: "Version: 1.7.0  |  Target Framework: Node.js / TypeScript  |  Compliance: PDF/UA-1 & WCAG 2.2",
      class: "muted",
    },

    // ── Section 1: Environmental Compliance ──────────────
    {
      type: "heading",
      text: "1. Environmental Compliance Profiles",
      options: { level: 2 },
    },
    {
      type: "table",
      rows: [
        [
          {
            text: "System Profile Requirement",
            header: true,
            bold: true,
            scope: "row",
          },
          { text: "Minimum Operational Standard" },
        ],
        [
          {
            text: "Node.js Environment",
            header: true,
            bold: true,
            scope: "row",
          },
          { text: "v18.12.0 LTS or superior runtime engine" },
        ],
        [
          {
            text: "Font Embedding Engine",
            header: true,
            bold: true,
            scope: "row",
          },
          { text: "TrueType (.ttf) or OpenType (.otf) with full Unicode maps" },
        ],
        [
          { text: "Metadata Engine", header: true, bold: true, scope: "row" },
          {
            text: "XMP (Extensible Metadata Platform) schema injection reader",
          },
        ],
      ],
      options: {
        headerColumns: 1,
        borders: "all",
        borderColor: TABLE_BORDER,
        headerBackground: TABLE_HEADER,
      },
    },

    // ── Section 2: Installation ───────────────────────────
    {
      type: "heading",
      text: "2. Package Installation Pipeline",
      options: { level: 2 },
    },
    {
      type: "paragraph",
      text: "Pull the package binaries down from your private registry endpoints using standard shell environment commands:",
    },
    {
      type: "table",
      rows: [
        [
          { text: "Phase", header: true, bold: true },
          {
            text: "Terminal CLI Command Execution String",
            header: true,
            bold: true,
          },
        ],
        [
          { text: "Step 1", header: true, scope: "row" },
          "npm config set @barrierbreak:registry=https://npm.barrierbreak.net",
        ],
        [
          { text: "Step 2", header: true, scope: "row" },
          "npm install @barrierbreak/a11ydocs-pdf",
        ],
      ],
      options: {
        headerRows: 1,
        headerColumns: 1,
        borders: "all",
        borderColor: TABLE_BORDER,
        headerBackground: TABLE_HEADER,
      },
    },

    // ── Section 3: Document Root Definitions ─────────────
    {
      type: "heading",
      text: "3. Tagged Document Root Definitions",
      options: { level: 2 },
    },
    {
      type: "paragraph",
      text: "To maintain legal compliance profiles, you must explicitly declare document languages and screen-reader landscape variables:",
    },
    {
      type: "table",
      rows: [
        [
          { text: "Configuration Option", header: true, bold: true },
          { text: "Value Variable Input", header: true, bold: true },
          { text: "A11y Screen Reader Purpose", header: true, bold: true },
        ],
        [
          { text: "language", header: true, scope: "row" },
          { text: "en-US" },
          {
            text: "Forces correct pronunciation synthesizer engine activation",
          },
        ],
        [
          { text: "structureRoot", header: true, scope: "row" },
          { text: '"Document"' },
          { text: "Initializes the primary parent tree tag structural layer" },
        ],
        [
          { text: "tagged", header: true, scope: "row" },
          { text: "true" },
          {
            text: "Enables explicit reading order flow boundaries throughout parsing",
          },
        ],
      ],
      options: {
        headerRows: 1,
        borders: "all",
        borderColor: TABLE_BORDER,
        headerBackground: TABLE_HEADER,
      },
    },

    { type: "pageBreak" },

    // ── Section 4: Structural Component Mappings ─────────
    {
      type: "heading",
      text: "4. Accessible Structural Component Mappings",
      options: { level: 2 },
    },
    {
      type: "paragraph",
      text: "When passing multi-dimensional elements across the framework parser grid, map columns properties safely to clear semantic nodes.",
    },
    {
      type: "heading",
      text: "4.1 Tabular Component Configuration Schema",
      options: { level: 3 },
    },
    {
      type: "table",
      rows: [
        [
          { text: "Raw Data Property", header: true, bold: true },
          { text: "Required Layout Tag Property", header: true, bold: true },
          { text: "Screen Reader Action Output", header: true, bold: true },
        ],
        [
          { text: "header: true", header: true, scope: "row" },
          { text: "Maps cell directly to TH element" },
          { text: "Announces coordinates context to user" },
        ],
        [
          { text: "bold: true", header: true, scope: "row" },
          { text: "Injects weight properties securely" },
          { text: "Maintains clean structural layout rules" },
        ],
        [
          { text: "options.headerRows", header: true, scope: "row" },
          { text: "Binds repeating headers explicitly" },
          { text: "Maintains context reference on layout splits" },
        ],
      ],
      options: {
        headerRows: 1,
        borders: "all",
        borderColor: TABLE_BORDER,
        headerBackground: TABLE_HEADER,
      },
    },

    // ── Section 5: Deployment Checklist ──────────────────
    {
      type: "heading",
      text: "5. PDF/UA-1 Deployment Checklist",
      options: { level: 2 },
    },
    {
      type: "list",
      items: [
        {
          body: "Always use explicit layout tag rules on your footers ('Artifact' or 'P') to prevent reading sequence disruption.",
        },
        {
          body: "Provide alternative descriptive strings explicitly whenever rendering visual chart files or svg layout structures.",
        },
        {
          body: "Maintain logical structural level indexing pipelines consistently (e.g., skip from Level 1 straight down to Level 3 is prohibited).",
        },
        {
          body: "Verify output binaries using validation automation engines like PAC3 or Adobe Accessibility Checker prior to deployment.",
        },
      ],
    },
  ],

  footer: ({ pageNumber, totalPages }) => [
    {
      type: "paragraph",
      text: "Accessibility Documentation",
      options: {
        fontSize: 10,
        tag: pageNumber === totalPages ? "P" : "Artifact",
      },
    },
  ],

  pageNumber: { region: "footer", align: "right" },
});

export default doc;

Key techniques

Technique	Purpose
class: "muted" on paragraph	Applies the named muted style (smaller font, grey color) to the version line without inline style overrides
headerColumns: 1 only	Used for the compliance table where there is no top header row — only row labels
headerRows: 1 + headerColumns: 1	Used for the installation table so each command cell is associated with both its column header and its step label
headerRows: 1 + scope: "row"	Used for the three-column reference tables where each row is an independent entry keyed by its first cell
borders: "all"	Draws borders around every cell rather than just the table's outer edge
borderColor	Sets the border line color, pulled from the shared TABLE_BORDER constant for consistency across every table
headerBackground	Applies a background fill to header rows/columns so they're visually distinguishable from data cells
Plain strings as data cells	Valid wherever a cell needs no styling — avoids unnecessary cell object verbosity
level: 3 headings	Introduces subsections under a section heading; requires a matching heading3 style entry
pageBreak block	Separates the installation and configuration half of the manual from the structural mapping section
No logo, no encryption	A plain documentation PDF requires no asset fetching or encryption block — createDocument stays minimal

PDF/UA conformance

This template targets conformance: "pdfua-1". To keep the document valid:

• Heading levels must not skip — a level: 3 heading must always be preceded by a level: 2 heading in the same section.
• Decorative repeated elements such as intermediate-page footers should use tag: "Artifact".
• tagged: true and structureRoot: "Document" are required at document creation.