PDFa11y

Why now

• April 2024: DOJ finalized the ADA Title II web and app rule
• State and local governments, and public universities, were put on notice
• Deadlines have slipped, but the obligation has not
• HTML pages get audited. PDF libraries mostly do not.

The remediation market

Prevention over remediation

Heavily inspired by Editoria11y: immediate feedback, right where editors work.

Built with a client who wanted prevention and education, not another subscription.

Open source and free by design

• A structural scan of a PDF does not belong behind a paywall
• Published on Drupal.org: drupal.org/project/pdfa11y
• Runs on your Drupal host, no third-party service
• Parser: smalot/pdfparser (LGPL 3.0) as a Composer dependency

Upload to result

Typical scan time is seconds, depending on file size. Results are stored per file and per media item.

Six checks today

Extensible by design

Each check is a plugin. Add your own with an attribute and one method.

#[AccessibilityCheck(
  id: 'figure_alt_text',
  label: new TranslatableMarkup('Figures have alt text'),
)]
final class FigureAltTextCheck extends AccessibilityCheckBase {
  public function check(Document $document): CheckResult {
    // Walk the structure tree for /Figure nodes without /Alt.
  }
}
          

Views field and filter plugins ship with the module, so any report is just another view.

PDFs are not web pages

• Editoria11y can point at the broken heading on the page
• A PDF only renders inside a viewer. There is no reliable way to overlay a widget on every viewer, and many people do not use a browser at all.
• So PDFa11y reports next to the file, not on top of it

Needs a human

• Alt text quality
• Whether the right text is tagged as a heading
• Reading order on visually complex pages
• Whether form fields are labeled meaningfully

Pair the module with editor training. The checks catch what can be caught mechanically.

Skipped, with a reason Skipped

• Missing file. The media record points at nothing. Usually a leftover from a delete or migration.
• Cannot be read right now. Remote storage such as S3 timed out. Temporary; retry later.
• Encrypted or restricted. Fix: re-export with no security and re-upload.
• Corrupt or malformed. Broken export, truncated upload, or not really a PDF.

Protecting the server

• Too large. Over the configured size limit, so we never start.
• Packed with images. Scanned plats and drawings can be small on disk and hundreds of MB decompressed. We estimate up front and skip what would exhaust memory.
• Too slow or too hungry. Time and memory are capped per file, so one bad file never derails a bulk scan.

Rolling this out on real libraries is what produced this list.

Where results show up

• Per media item: an Accessibility tab with every check and message
• Site-wide: /admin/reports/pdf-accessibility with pass, fail, and error counts
• Anywhere else: Views field and filter plugins for your own listings
• Editors: a status badge on embedded documents, if the theme prints it

Two safe ways to scan a library

Queue mode for unattended backfills. Each file runs in its own worker, memory is reclaimed between items.

drush pa:check --bundle=document --missing-only --queue
drush queue:run pdfa11y_check
          

Chunked sync runs when you are watching and SSH sessions have a time cap.

drush pa:check --bundle=document --missing-only --limit=1500 --format=summary
          

Configuration

• Editor instructions: link your own remediation guide
• Warn or block: block failing uploads, with a bypass permission
• Minimum PDF version and which checks run
• Permissions: administer, run checks, view reports, bypass

/admin/config/media/pdf-accessibility

Roadmap

• Editoria11y integration. A custom check that surfaces PDF fails and errors on embedded media, right in the editor.
• Missing alt text. PDF figures have an alt concept too.
• More settings. Size and memory limits in the UI, not just config overrides.
• Many Editoria11y HTML checks have a PDF structure equivalent waiting to be written.

Get involved

• Try it: drupal.org/project/pdfa11y
• Feature requests and bugs: the issue queue
• Need an accessibility audit, an implementation, or want to fund a check? Let's talk.