HTML to PDF Conversion: How To Create Accessible PDFs (aka Tagged PDFs) Documentation

Tags determine how a PDF’s structure and graphics are described to assistive devices, such as screen readers. For that reason, accessible PDFs are often called “tagged PDFs.”

The standards for creating tagged PDFs were created in 2012 as the PDF/Universal Accessibility standard (also referred to as PDF/UA or ISO-14289). Tagging and PDF/UA have become critical components of meeting the WCAG 2.0 and Section 508 accessibility standards.

As it becomes evident, knowing how to create tagged PDFs is important if you want your documents to be accessible and in compliance with the relevant standards. In this article we offer you a comprehensive but easy-to-follow guide on creating tagged PDFs, with step-by-step instructions.

Creating an Accessible PDF

Creating accessible, tagged PDFs is incredibly easy with DocRaptor’s HTML-to-PDF API. Our PDF generation engine, Prince, automatically creates most of the relevant tags. Prince turns <h1> elements into header tags, <blockquote> elements into quote tags, etc. Tagging can be customized and adjusted further through CSS.

The majority of the WCAG and Section 508 criteria are met through DocRaptor’s automatic tagging. Some additional modifications may be required to completely fulfill the requirements. This document will review the common problem areas for both WCAG and Section 508 as well as inspection tools for verifying your document’s compliance.

Step 1: Enable Tagging

To create a tagged document with DocRaptor, set the prince_options[profile] parameter to PDF/UA-1. That’s all that’s needed to enable automatic tagging when converting HTML to PDF. Though, as mentioned above, more tweaking may be necessary to make a fully accessible PDF.

Step 2: Declare Languages

Ensure that your HTML declares the document’s language. <html lang=’en’> is for English, as an example. If your document uses mixed languages, wrap each section in its own language declaration, such as <span lang=’es’>.

Step 3: Don’t Rely on Color

The WCAG criteria state: “Color is not used as the only visual means of conveying information, indicating an action, prompting a response, or distinguishing a visual element.”

Don’t use color alone to indicate that something is good, bad, clickable, actionable, or required. It’s OK to use color in these scenarios, but also use text alongside color, and ensure links have underlines.

Step 4: Use Contrast

It’s difficult to read text with low contrast, that is, where the foreground and background have similar light levels. WCAG and Section 508 require a minimum contrast ratio of 4.5:1 for normal text and a 3:1 for large text. WebAIM has an excellent contrast checker with visual examples.

Step 5: Check Alternative Text and Abbreviations

Make sure all your images and graphics have an alternative text attribute (<img alt=”DocRaptor Logo” />) and any abbreviations have an explanatory title attribute (<abbr title="Application Programming Interface”>API</abbr>),

Step 6: Create a Title

Assistive devices use a document’s title, not the filename. Creating a title in DocRaptor is as simple as having a <title> element in your HTML. While not required, you can set additional PDF metadata with HTML meta elements:

<meta name="author" content="DocRaptor Support Team"/>
<meta name="subject" content="How to use HTML to PDF to create an accessible PDF"/>
<meta name="keywords" content="accessibility, html to pdf, wcag, section 508"/>
<meta name="date" content="2012-12-12"/>
<meta name="generator" content="DocRaptor"/>

Step 7: Review Bookmarks

In a PDF, the term bookmarks refers to the outline or table of contents shown in the PDF reader. The outline is important for users to quickly navigate through your document and jump from section to section.

By default, DocRaptor automatically generates these bookmarks from header tags (such as <h1>). Ensure that these bookmarks accurately reflect the outline of your document, and that there are not any bookmarks missing. If necessary, you can use CSS to adjust which elements are used to create bookmarks.

Step 8: Review and Customize Tagging

Adobe Acrobat Pro is the most commonly used tool for editing and reviewing PDFs. Within Acrobat, go to View > Show/Hide > Navigation Panels > Tags to enable the tags panel. From that panel, you can view your document’s tags and the document structure they create.

Verify Reading Order

Assistive devices will read the tags in the order you specify. As it’s common in HTML to use CSS to visually shift the order of content and code, you need to ensure that the tagged content is in the correct order. If necessary, change the order of your HTML to match the desired reading order and then use CSS to visually rearrange the content.

Tag Every Element

While DocRaptor automatically creates tags, you’ll need to double-check that all the content is tagged correctly. This includes:

Table headers and captions: Do your table tags make sense if read aloud?
Image alt text: Do meaningful images have alternative text describing the image?
Lists: A list must be tagged as a list. You may need to add custom CSS to tag non-<li> elements as lists.
Abbreviations: Do any abbreviations need to be expanded with alternative text?
Table of Contents: These have their own tag, and because this isn’t a standard HTML element, we can’t automatically tag the TOC.
Bibliography and footnotes: This should be tagged as BibEntry.
Quotes: While we’ll automatically tag <blockquote> elements as a BlockQuote, ensure all your quotes are using blockquotes or have custom tagging set up.

You can tag elements through CSS via the -prince-pdf-tag-type property. For example, you can tag your table of contents with this code::

#table-of-contents {
  -prince-pdf-tag-type: TOC;
}

#table-of-contents li a {
  -prince-pdf-tag-type: TOCI; 
}

The full list of tag options includes:

auto
Part
Art
Sect
Div
Index
BlockQuote
Caption
TOC
TOCI
P
H1
H2
H3
H4
H5
H6
OL
UL
LI
Lbl
DL
DL-Div
DT
DD
Span
Quote
Table
BibEntry
Code
Figure
Formula
Artifact
none

The Adobe documentation contains a detailed description of each tag type.

Hide Unnecessary or Repeating Elements

If an element is merely decorative in nature, you should disable tagging of that element with:

#awesome-decoration {
  -prince-pdf-tag-type: none;
}

Repeating elements with repetitive information, such as headers and footers merely containing the document title, should be hidden after the first usage. You can do that with code like:

footer:not(:first-child) {
  -prince-pdf-tag-type: none;
}

If the header contains actual information such as page numbers, you should leave that part of the element.

Tag ARIA Roles

DocRaptor does not tag any ARIA roles automatically. If any of your roles should be tagged, you can do that through CSS:

div[role="article"] {
  -prince-pdf-tag-type: Art;
}

Verifying Compliance

The above steps are everything most documents need to meet accessibility standards. The following tools let you test the HTML-to-PDF API output for compliance:

CommonLook PDF Validator is a free Adobe Acrobat plugin that tests against Section 508, WCAG 2.0 AA, PDF/UA, and HHS standards.
PDF Accessibility Checker (PAC), is another free tool for testing for PDF/UA compliance. TaggedPDF.com has a detailed troubleshooting section for fixing PAC errors.
axesPDF is a paid remediation tool. In addition to testing for PDF/UA, WCAG, and Section 508 compliance, it will assist in directly fixing any issues found.
pdfGoHTML is a free Adobe Acrobat plugin that provides a more robust PDF tag interface for easier document evaluation. It doesn’t directly test against any standards.

Additional Support

While the DocRaptor team members are not accessibility experts, if you encounter any issues with generating your tagged PDF or using the Prince CSS, please contact us at support@docraptor.com. We’d be happy to help!

HTML to PDF Conversion: How To Create Accessible PDFs (aka Tagged PDFs)