Please just tell me what to
do
OK, OK. All of this context is important because you
will run into issues, and I found it very hard to
understand those issues until I understood everything I said above. But
let’s get to it.
You need to use TeX Live 2025 or newer. I personally like to do a “full” install of TeX Live
outside of any package system so that I can easily maintain multiple
versions. Parts of these instructions also require you to update the
2025 distribution with tlmgr update --all, because this
functionality is being actively developed.
You can also jump straight to the usage
instructions, but I’ve found that it’s easier to debug if you
incrementally turn on features as described below.
Step 1: PDF 2.0
To activate the PDF management functionality, add this as the first
line of your LaTeX file and try compiling with LuaLaTeX (or
pdfLaTeX):
\DocumentMetadata{lang=en-US}
If you use (m)any packages, your file may well not compile. If it
does compile, then the output should be PDF 2.0 instead of the usual PDF
1.5 or 1.7, and it will score slightly higher on Canvas. (You can check
the version easily with file.)
In the more likely event that it doesn’t, try to figure out what’s
causing the error. Check the list of
package compatibility with tagging, and if appropriate, open a GitHub
issue with the LaTeX Tagged PDF Project. I (and many PL folks)
extensively use a package called mathpartir that was
untested until I opened an
issue. (Note to mathpartir users: use the patch to the
mathpar environment suggested by David Carlisle in this
GitHub comment.)
The most problematic packages are those that modify LaTeX internals
and/or reimplement a lot of core functionality; some of these may never
be fully supported, and the Tagged PDF Project may in fact hasten their
demise independently of whether you want accessible PDFs. For an example
of modifying internals, I will probably have to switch from the
unmaintained cleveref to zref-clever soon due
to some regressions in TeX Live 2025. For an example of reimplementing
core functionality, I can only hope that memoir will
eventually be supported. And beamer is completely
hopeless.
Now we have a PDF 2.0 file tagged only with its language. That was
the hardest part for me: I had to open a ticket about
mathpartir, tweak a few packages, and debug inconsistencies
between pdfLaTeX and LuaLaTeX. (The diffpdf package on
Ubuntu was quite helpful for this.)
To actually tag your content, just replace the first line with:
\DocumentMetadata{lang=en-US,tagging=on}
This enables automatic tagging for many basic LaTeX features:
headings, figures, tables, etc. You can use TeX Live’s
show-pdf-tags command-line utility to
see what is and isn’t tagged.
You will have to manually tag images (with alt text) and tables (by
indicating which rows are “header rows”), as described in the usage
instructions. Note that Ally complains about presentation tables
without header rows. (I had to mistag some tables that I use for
alignment in order to satisfy Ally.)
At this point, Ally will complain that all of the mathematical
expressions in your document are “images missing alternative
descriptions.” (I’m not sure why this is the warning message, because
they are definitely not images.)
To make our mathematics accessible, we can embed alternative MathML
and/or plain text into the PDF. The former is the best approach, but
only the latter satisfies Ally. It’s easy enough to do both in LuaLaTeX,
by replacing the first line with:
\DocumentMetadata{lang=en-US,tagging=on,tagging-setup={math/setup=mathml-SE,math/alt/use}}
The math/alt/use part tags mathematical expressions with
their actual LaTeX source as their plain alt text. (Be
aware that this exposes the names of your macros, your shameful LaTeX
code, etc.) The math/setup=mathml-SE part uses
luamml to generate an intermediate file called
filename-luamml-mathml.html with MathML representations of
every mathematical expression, and then embed these in the PDF. These
two options are independent.
At this point in the process, my PDFs score 94-100% on Ally.