September 13, 2021 · reala11y team

Accessible PDFs on WordPress (and when to offer HTML instead)

Why PDFs are so often inaccessible, the tagging, reading-order and alt-text basics that fix them, and why an HTML alternative is usually the better answer on WordPress.

Sooner or later a WordPress site accumulates PDFs: a menu, a price list, a council meeting agenda, an annual report someone exported from InDesign. They get uploaded to the Media Library, linked from a page, and forgotten. And most of them are, to a screen-reader user, a closed door.

PDFs aren’t exempt from accessibility expectations just because they’re attachments rather than web pages. A PDF you publish is content you’re responsible for. The frustrating part is that a PDF can be made reasonably accessible — it’s just that almost nobody does the work, and the tools make it easy to skip.

Why PDFs are so often inaccessible

A PDF describes where ink goes on a page. That’s its job and its problem: visually it looks finished, but underneath there may be no information about what any of that ink means. Common failures:

• No tags. Accessibility in PDF relies on a hidden “tag tree” that marks this text as a heading, that as a paragraph, this as a list, that as a table. A PDF exported without tags is, to a screen reader, an unstructured blob — or, if it was scanned, an image of a page with no real text at all.
• Broken reading order. Even tagged PDFs often have a tag order that doesn’t match the visual layout, so a two-column document reads straight across both columns, interleaving nonsense.
• No alternative text on images, charts, and logos.
• No document language set, so the screen reader may use the wrong pronunciation rules.
• Scanned documents with no OCR — pure pictures of text, completely unreadable to assistive tech and unsearchable.

The basics that fix a PDF

If you must publish a PDF, fix it at the source — ideally in the authoring tool, because retrofitting is painful.

1. Start tagged. Word, Google Docs, and InDesign can all export tagged PDFs if you use their built-in styles. The key move is to use real heading styles (Heading 1, Heading 2) and real list and table features rather than faking structure with bold text and tab stops. Structure in the source becomes tags in the export.

2. Check and fix the tag tree. Acrobat Pro’s Accessibility tools include a “Reading Order” panel and a tag tree you can correct by hand. Free alternatives like the open-source PAC (PDF Accessibility Checker) will report problems even if they can’t fix them. The big things to verify: every heading is tagged as a heading, the reading order is correct, and tables have header cells marked.

3. Add alt text to images. Same principle as on the web — meaningful images get a description, decorative ones get marked as artifacts so they’re skipped.

4. Set the document title and language. In the document properties, give it a real title (shown in the screen reader and the browser tab) and set the language. Set the document to display its title rather than the filename.

5. OCR anything scanned. Run optical character recognition so the text is real text, then tag and check it like any other document.

On WordPress: offer the HTML version

Here’s the honest recommendation: for most content, don’t publish a PDF at all — publish a web page.

WordPress is exceptionally good at producing accessible HTML when you use it normally. A page built from the block editor — real headings, real lists, images with alt text entered in the Media Library — is structured, responsive, searchable, easy to update, and reads well in a screen reader, with none of the tagging overhead a PDF demands. A council agenda or a price list is almost always better as a page than as a download.

When a PDF genuinely has to exist (a form people print, a formal report with a fixed layout, a document mandated in that format), the strong pattern is PDF plus an HTML equivalent:

<p>
  <a href="/files/2021-annual-report.pdf">
    Download the 2021 annual report (PDF, 2.4&nbsp;MB)
  </a>
  — or <a href="/2021-annual-report/">read it as a web page</a>.
</p>

Two details in that snippet matter. State that the link is a PDF and give its size, so nobody’s surprised by a download — and offer the web version right next to it. The HTML page becomes the accessible path; the PDF is there for people who specifically want it.

A practical WordPress tip: name files sensibly before upload (2021-annual-report.pdf, not final_v3_FINAL.pdf), because the filename often becomes the visible context. And remember the Media Library can hold dozens of forgotten PDFs from years of uploads — worth an audit.

Where tooling helps, and where it doesn’t

PDF accessibility is mostly a manual, authoring-side discipline; there’s no render-time filter that retags a document for you. An automated checker (PAC, Acrobat’s checker) can tell you a PDF is untagged, has no language, or is image-only — useful triage — but a human still has to fix the structure and judge whether alt text and reading order are right. The same honesty that applies to web scanning applies here: automated checks surface a fraction of the issues, and the rest is judgement. On the web side, reala11y scans the HTML your site outputs and fixes code-level issues at the source; for PDFs, the most reliable accessibility win is usually to publish the HTML page in the first place.

The honest takeaway

PDFs are inaccessible by default because they encode appearance, not meaning — and fixing that means tagging, correcting reading order, adding alt text, and setting a language, all in the authoring tool before you export. On WordPress, the better move is usually to skip the PDF and publish a properly structured page, or to offer both and label the download clearly. Automated checkers help you find unstructured documents but can’t repair them, detecting only a slice of the real issues; human review does the rest. Do that work and your documents move toward WCAG 2.2 AA conformance — which is the honest framing. No format and no tool is accessible on its own; the structure you give it is what counts.