stability: Beta

Tag footnote references and bodies

At a glance

Render footnote references and footnote bodies over Connect so the structure tree carries the PDF 2.0 footnote roles. The inline marker becomes a footnote/endnote reference, and the footnote text becomes a note body, with a reciprocal back-reference between them. Three HTML shapes produce the same output: a link inside a superscript, an explicit Accessible Rich Internet Applications (ARIA) role="doc-noteref", and an <aside class="footnote"> body container. Verification uses the Pro-tier accessibility tool. NextPDF discovers it with class_exists() and registers it only when nextpdf/premium is installed alongside the server.

A passing accessibility-tool result is an accessibility check, not an independent conformance certification.

Install

composer require nextpdf/server

Confirm that the Pro accessibility tool is available with a tools/list call; see /connect/tool-catalog/.

Conceptual overview

PDF 2.0 defines dedicated footnote/endnote structure types and the relationship between a reference and its body (PDF/UA-2 §8.2.5). A footnote reference must be associated with its body (PDF/UA-2 §8.2.5), so a screen reader can announce the reference and follow the link to read the note. Both the reference and the body must be reachable through the structure tree (PDF/UA-2 §8.2.4).

The pipeline recognizes three reference shapes:

<sup><a href="#fn-N">N</a></sup> — link-in-superscript shorthand.
<sup role="doc-noteref" aria-describedby="fn-N">N</sup> — explicit Digital Publishing Accessible Rich Internet Applications (DPUB-ARIA) role; aria-describedby is forwarded as the back-reference target.
<aside class="footnote" id="fn-N">…</aside> (or role="doc-footnote") — the body container, emitted as a note body with an internal reference back to the matching reference.

API surface

Verify tool names against the running registry with tools/list. The catalog of record is /connect/tool-catalog/. This recipe uses core document and HTML tools plus the Pro accessibility check, and does not restate a tool count.

Code sample — Quick start

Create a tagged document with a language set, then add the link-shorthand reference:

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "create_pdf",
    "arguments": { "page_size": "A4", "title": "Footnote Patterns", "language": "en" }
  }
}

Code sample — Production

Emit both references and both bodies in one HTML add, then run the check:

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "add_html",
    "arguments": {
      "document_id": "<id from create_pdf>",
      "html": "<p>Revenue grew 24%<sup><a href=\"#fn-1\">1</a></sup>.</p><p>Margin 33%<sup role=\"doc-noteref\" aria-describedby=\"fn-2\">2</sup>.</p><aside class=\"footnote\" id=\"fn-1\"><p>YoY vs prior year.</p></aside><aside class=\"footnote\" id=\"fn-2\" role=\"doc-footnote\"><p>(Revenue − OpEx) / Revenue.</p></aside>"
    }
  }
}

The accessibility check reports the paired reference/body roles and the reciprocal back-references.

Edge cases & gotchas

Reference but no body (or body but no reference) is reported by the check; every reference needs a matching body and vice versa.
id mismatch between aria-describedby and the body id leaves the pair unresolved (case-sensitive).
Superscript anchor to an external URL emits a plain link, not a footnote reference; use the explicit role for an external target.
Bare <aside> without class/role is treated as a landmark, not a note body. Add class="footnote" or role="doc-footnote".
Tool absent. Without nextpdf/premium, the Pro accessibility tool is not registered, so verification fails with an unknown-tool error.

Performance

The frontmatter budget is a documentation cap; footnote pairing is part of the normal structure pass.

Security notes

Not applicable beyond the general Connect transport guidance.

Conformance

PDF/UA-2 mapping

Claim	Clause
Footnote/endnote structure types and reference/body relationship	PDF/UA-2 §8.2.5
A footnote reference is associated with its body	PDF/UA-2 §8.2.5
Reference and body reachable through the structure tree	PDF/UA-2 §8.2.4

Tag → ISO 32000-2 §14.9 cross-ref

The reference and body use the PDF 2.0 footnote/endnote standard structure types. The reciprocal back-reference is the accessible-footnote contract.

WCAG 2.2 mapping

Associated footnote reference and body support Web Content Accessibility Guidelines (WCAG) 2.2 SC 1.3.1 (Info and Relationships) and SC 2.4.1 (Bypass Blocks) at the content level.

A passing accessibility-tool result is an accessibility check, not a conformance certification; an independent checker makes that determination.

Commercial context

The accessibility check tool is Pro-tier and registers only when nextpdf/premium is installed alongside the server.

Connect specifics

Transport availability (MCP / REST / gRPC)

create_pdf, add_html, and the accessibility check are invoked identically over Model Context Protocol (MCP), REST, and gRPC through the shared tool executor.

HITL risk tier

Document creation and HTML ingestion are caution-level; the accessibility check is read-only. None is approval_required by default. See /connect/hitl-risk-tiers/.

Confirmation gate JSON envelope

These tools do not trigger the gate unless an operator override raises one to approval_required. The envelope and single-use token contract is in /connect/hitl-risk-tiers/.