accessible-pdf

name	accessible-pdf
user_invocable	true
description	Make a LaTeX document produce accessible tagged PDFs (PDF/UA-1, PDF/A-2b). Creates a non-destructive copy and Makefile target. Use when the user needs accessible or tagged PDFs.

accessible-pdf — Accessible PDF from LaTeX

Transform a LaTeX document to produce tagged, screen-reader-friendly PDFs compliant with PDF/UA-1 and PDF/A-2b. Applies preamble changes and switches the build to LuaLaTeX. The user chooses whether to edit the original file in place or create a -accessible copy with a separate Makefile target.

Reference: https://yyahn.com/wiki/Accessible-PDF-from-LaTeX/

When to Use

• "make my PDF accessible", "tagged PDF", "PDF/UA", "screen reader"
• ADA/accessibility compliance for any LaTeX document (CV, syllabus, report, paper)

Prerequisites

• TeX Live 2025+ (the \DocumentMetadata tagging framework is recent)
• LuaLaTeX and latexmk (both ship with TeX Live)
• pdfinfo from poppler (for verification): brew install poppler on macOS
• make (optional) — used for the Makefile target; latexmk can be run directly instead

Windows users: make is not standard on Windows — run latexmk -lualatex <basename> directly instead of using the Makefile. Install poppler via choco install poppler or scoop install poppler.

Check early: run lualatex --version and pdfinfo -v. If either is missing, tell the user what to install and stop.

Workflow

Phase 1: Find, analyze, and plan

1. Find the document

Use the user-provided path. If none given, glob for **/*.tex files containing \begin{document}. If multiple matches, ask the user to pick. No assumptions about directory structure — this could be a CV, syllabus, report, or paper.

2. Read the preamble

Read everything before \begin{document}. Identify:

• \documentclass line and options
• All \usepackage lines
• Whether \DocumentMetadata already exists
• Whether hyperref / \hypersetup already exists
• Font-related packages: inputenc, fontenc, fontspec, mathpazo, mathptmx, newtxtext, newtxmath, helvet, courier, libertine, libertinus, lmodern, inconsolata, etc.
• Symbol packages: marvosym, pifont, wasysym, etc.
• \title{...} and \author{...} content (needed for hypersetup metadata)
• Language settings from babel or polyglossia

If the document already has \DocumentMetadata and uses fontspec, it may already be configured for accessibility. Note this in the questions below.

3. Ask the user

Present all decisions as a single numbered list so the user can answer in one message:

1. Edit in place or create a copy? Edit the original .tex file, or create <basename>-accessible.tex alongside it? (Multi-file projects: only the main file changes either way.)
2. Makefile? Add a Makefile target, or just run latexmk directly? (If a Makefile already exists, note this.)
3. Platform? macOS, Linux, or Windows? (Affects install instructions for poppler and whether make is available.)
4. Build and verify now? Build the PDF and check tagging after applying changes, or stop after editing?

Use the answers to tailor Phases 2–4 below.

Phase 2: Apply transformations

4. Apply transformations

Apply these 5 ordered changes to the target file (either the original or the -accessible copy):

a) Add \DocumentMetadata block

Insert before the \documentclass line:

\DocumentMetadata{
  lang = en,
  pdfstandard = a-2b,
  pdfstandard = ua-1,
  pdfversion = 2.0,
  testphase = {phase-II},
}

If the document uses babel or polyglossia with a non-English language, use the appropriate language code instead of en.

b) Replace Type1 font packages with OpenType equivalents

Add \usepackage{fontspec} after \documentclass (if not already present). Then apply these replacements:

Remove	Replace with
\usepackage[utf8]{inputenc} (any options)	Remove entirely — LuaLaTeX handles UTF-8 natively
\usepackage[T1]{fontenc} (any options)	Remove entirely — fontspec handles encoding
\usepackage{mathpazo} or \usepackage[sc]{mathpazo}	\setmainfont{TeX Gyre Pagella}
\usepackage{mathptmx}	\setmainfont{TeX Gyre Termes}
\usepackage{newtxtext}	\setmainfont{TeX Gyre Termes}
\usepackage{helvet} (any options)	\setsansfont{TeX Gyre Heros}
\usepackage{courier}	\setmonofont{TeX Gyre Cursor}
\usepackage{lmodern}	Remove entirely — Latin Modern is the LuaLaTeX default
\usepackage{inconsolata}	\setmonofont{Inconsolatazi4-Regular.otf}[BoldFont=Inconsolatazi4-Bold.otf]
\usepackage{libertine} or \usepackage{libertinus}	\setmainfont{Libertinus Serif}

Math font packages (newtxmath, eulervm, mathpazo with math features): flag these for the user to review rather than silently replacing. Math font compatibility with LuaLaTeX can be tricky. Add a % TODO: review math font compatibility comment.

For any font package not in the table above, add a % TODO: find OpenType equivalent for <package> comment and warn the user.

c) Add/update hyperref accessibility metadata

If hyperref is not loaded, add \usepackage{hyperref}.

Add or merge into the existing \hypersetup:

\hypersetup{
  pdftitle={<from \title{}>},
  pdfauthor={<from \author{}>},
  pdflang={en},
  pdfdisplaydoctitle=true,
}

Preserve any existing \hypersetup keys (like colorlinks, linkcolor, etc.) — only add the accessibility-specific keys that are missing. pdfdisplaydoctitle=true is required for PDF/UA.

d) Replace symbol font packages

Remove	Add	Command mappings
\usepackage{marvosym}	\usepackage{fontawesome5}	\Letter -> \faEnvelope, \Mundus -> \faGlobe, \Telefon -> \faPhone

Search the document body (not just the preamble) for uses of replaced commands and apply the mappings. For commands with no known mapping, leave the original with a % TODO: replace with accessible equivalent comment.

pifont and wasysym: keep them but flag for review if heavily used — some of their symbols may lack Unicode mappings.

5. Show the user a summary

List all changes made, organized by category (metadata, fonts, hyperref, symbols). Highlight any % TODO: items that need manual attention.

Phase 3: Makefile target (if requested)

Skip this phase if the user declined a Makefile.

6. Add build target

Copy mode — append or create a target:

# Accessible PDF (PDF/UA-1, PDF/A-2b) — built with LuaLaTeX
<basename>-accessible.pdf: <basename>-accessible.tex
	latexmk -lualatex <basename>-accessible

In-place mode — if a Makefile exists with a pdflatex target, update it to use latexmk -lualatex. Otherwise, append or create:

# Build with LuaLaTeX for accessible tagged PDF
<basename>.pdf: <basename>.tex
	latexmk -lualatex <basename>

Phase 4: Build and verify (if requested)

Skip this phase if the user declined building now.

7. Build

Run the appropriate command:

• Makefile: make <basename>-accessible.pdf (copy) or make <basename>.pdf (in-place)
• No Makefile: latexmk -lualatex <basename>-accessible (copy) or latexmk -lualatex <basename> (in-place)

If the build fails, diagnose:

• Missing fonts: suggest tlmgr install <font-package>
• Package conflicts with testphase: suggest downgrading to phase-I
• unicode-math conflicts: common with certain math packages — flag for user

8. Quick sanity check (pdfinfo)

Run pdfinfo <output>.pdf and check:

• Tagged: should be yes. If no, the \DocumentMetadata setup needs debugging.
• Title: should match the document title. If missing, \hypersetup wasn't applied correctly.
• Author: should be present.

This is a basic sanity check only — it confirms the PDF has tags and metadata but says nothing about whether the tags are correct or the reading order makes sense.

9. Present summary

Report:

• File locations and build command
• pdfinfo results (tagged, title, author)
• Any % TODO: items remaining
• Tell the user they must validate manually. This skill applies the right LaTeX changes, but real accessibility verification requires external tools:
  • PDFix Validate (https://pdfix.net/products/pdfix-validate/) — web-based PDF/UA validator; upload the PDF and review the report. This is the recommended first check.
  • PAC (PDF Accessibility Checker) — desktop tool, considered the gold standard for PDF/UA validation (Windows only).
  • macOS VoiceOver (Cmd+F5 in Preview) — test actual screen reader navigation.
  • axesCheck — another web-based checker, though it may flag issues that PDFix does not and vice versa.

Rules

• Flag uncertain font mappings with % TODO: rather than guessing
• Use testphase = {phase-II} as default — phase-III is more complete but conflicts with more packages
• If the document already appears configured for accessibility, confirm with the user before proceeding