| 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:
- 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.)
- Makefile? Add a Makefile target, or just run
latexmk directly? (If a Makefile already exists, note this.)
- Platform? macOS, Linux, or Windows? (Affects install instructions for poppler and whether
make is available.)
- 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:
<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:
<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
