PDF Tagger

A PDF is the easiest thing to share and the easiest thing to break

Exporting to PDF feels like the safe option. It looks the same everywhere, nobody can nudge your layout, and you can email it to anyone. That is exactly why so much gets sent that way, and exactly why so much of it is unusable for anyone relying on a screen reader.

A PDF stores where each piece of text sits on the page. It does not, by default, store what any of it is. You look at a line set in 28pt bold at the top of a slide and you know it is the title. A screen reader has no size to look at. It needs the file to say, in a structure tree, "this is a heading, and this is the paragraph under it, and these three things are a list". Without that tree there are no headings to jump between, no lists, no table rows, no descriptions for the images, and no reliable order to read it in.

Export a deck from Google Slides and you get exactly that: a file with no structure tree at all. Not a thin one, not a wrong one. None. The same goes for plenty of other exporters. Google Docs has a worse habit, which is exporting tags that exist but are nonsense, so checking tools report the document as tagged and everyone moves on.

Why it does not try to do the whole job on its own

It would be easy to make this fully automatic, and the result would be worse. A program can measure a font size, a position, the gap between two lines. There are limits to what that tells you:

• Is that bold line a heading, or the first few words of a sentence? Plenty of decks set the opening word of a paragraph larger and bolder. Call it a heading and you have put half a sentence into the list a screen reader user navigates by.
• Are those two columns a table, or two cards sitting side by side? Geometrically they are identical. One should be read across the rows, the other one card at a time, and reading a pair of cards as a table shreds both of them.
• Does that image mean anything? Only the person who put it there knows whether it is a chart carrying the argument or a swoosh behind the title. Getting this wrong in either direction is bad: a described decoration is noise, an undescribed chart is a hole in the document.

So the app measures everything it reasonably can, proposes a role for each item with a confidence score and a plain sentence explaining why, and puts the genuinely uncertain ones in a queue for you. You confirm, correct, merge, split, or drag things into a different reading order. The aim is to take the tedious ninety percent off your hands and be honest about the rest, not to produce a confident-looking file nobody checked.

What it actually builds

• Headings at sensible levels, with lists, quotes and captions kept out of them.
• Real tables, including borderless ones, with header cells scoped to their row or column and the reading order running across the rows.
• Figures with alt text you write, or mark as decorative so they are skipped.
• Links and form fields, labelled from the text next to them.
• A reading order you can see, click through against the page, and drag into place.
• Document language, title, and the flags a reader needs to show the title rather than the filename.

It checks its own work with veraPDF against all 106 PDF/UA-1 rules. That is bundled inside the app with a trimmed Java runtime, which is most of the download size, and the reason you get a real verdict instead of a promise. Everything happens on your machine: it is a local app with a local interface, and the only thing that ever leaves your Mac is whatever you choose to send.

The one optional exception is a switch in the top right. Turn it on, and if you have Claude Code or an Anthropic API key it will draft a description for each image and give the reading order a second look. It works out whether an image carries meaning at all or is just decoration, and tells you why it decided that, which is usually the part people find tedious. Everything comes back as a draft that still counts as outstanding until you have read it, only the image itself is sent rather than the whole page, and the app is perfectly usable with the switch off.

It never touches your pixels. Open the tagged file next to the original and they are identical; all that changed is the structure underneath.

Installing it

1. Download the zip and unzip it.
2. Drag PDF Tagger into your Applications folder.
3. The first time only: right-click the app and choose Open, then Open again when macOS asks. Double-clicking will be refused.

Using it

1. Open a PDF. The app reads it and proposes a structure.
2. Walk the pages. Each item shows what it was called, how confident that was, and why. Anything uncertain is collected into a review list so you are not hunting for it.
3. Fix what is wrong. Change a role, merge two fragments, split one that swallowed two columns, or drag an item to a different place in the reading order.
4. Describe the images, or mark them decorative.
5. Export. You get a conformance verdict on the way out.

There are two short guides in the app's downloads, one on installing and one on how it works. Both are, as you would hope, tagged.

The honest caveats

• This is a personal project and a work in progress. It is built in my own time, it has rough edges, and it is not a product. I use it and it does the job, which is a different claim from it being finished.
• Apple silicon Macs only, and not signed or notarised. See above.
• Review the output. The app is careful about flagging what it is unsure of, but it still proposes and you still decide. Do not ship a document you have not looked at.
• Tagging does not fix a bad document. If the text is 3:1 against a photo, or the content only makes sense if you can see the layout, structure will not save it. Tagging makes a good document reachable; it cannot make a poor one good.
• The real fix is upstream. If a document can live as a web page, it should. HTML gives you structure for free, reflows on a phone, and does not need a tool like this at all. PDF Tagger exists because "just send it as HTML" is not always an option, not because PDF is a good idea.

If you try it and something breaks, or it calls something a heading that plainly is not, I would genuinely like to know. Issues on the GitHub repo are the easiest way, or there is a contact link on the front page.