Skip to content

Commit 20749ae

Browse files
github-actions[bot]gordonwoodhullcwickham
authored
[Sync to prerelease] pdf accessibility blog post (#1941)
* pdf accessibility blog post --------- Co-authored-by: Gordon Woodhull <gordon.woodhull@posit.co> Co-authored-by: Charlotte Wickham <charlotte.wickham@posit.co>
1 parent 3fcacad commit 20749ae

3 files changed

Lines changed: 127 additions & 0 deletions

File tree

‎docs/blog/posts/2026-03-05-pdf-accessibility-and-standards/index.qmd‎

Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
---
2+
title: PDF Accessibility and Standards
3+
description: |
4+
Quarto 1.9 brings PDF accessibility and standards support, building on new tagging features in LaTeX and Typst.
5+
author: Gordon Woodhull
6+
date: "2026-03-05"
7+
image: thumbnail.png
8+
image-alt: "Quarto icon, PDF file icon, accessibility icon, and validation shield"
9+
---
10+
11+
{{< include ../_quarto-1.9-feature.qmd >}}
12+
13+
2025 was a big year for PDF accessibility. LaTeX and Typst both released support for PDF tagging and accessibility standards, just in time for new regulations in the [EU](https://en.wikipedia.org/wiki/European_Accessibility_Act) (June 2025) and [US](https://accessible.org/ada-title-ii-web-accessibility/) (April 2026).
14+
15+
Quarto 1.9 brings this support to you as a Quarto user.
16+
17+
## What PDF Standards Do
18+
19+
Currently LaTeX supports the newer UA-2 standard, and Typst supports the older UA-1 standard. Typst is likely to have UA-2 support later in 2026.
20+
21+
Both standards instruct the PDF renderer to provide screen readers:
22+
23+
* The semantic structure of the text (title, heading, paragraph, figure, etc)
24+
* The natural reading order
25+
* Spatial coordinates for highlighting and assistive navigation
26+
* Required metadata such as title and language
27+
28+
## How to enable a PDF Standard in Quarto
29+
30+
In Quarto 1.9, specify a PDF standard for your document or project with `pdf-standard`
31+
32+
::::: {layout-ncol=2}
33+
:::: {}
34+
**PDF (LaTeX)**
35+
36+
```yaml
37+
format:
38+
pdf:
39+
pdf-standard: ua-2
40+
```
41+
::::
42+
43+
:::: {}
44+
**Typst**
45+
46+
```yaml
47+
format:
48+
typst:
49+
pdf-standard: ua-1
50+
```
51+
::::
52+
:::::
53+
54+
`pdf-standard` takes a single standard name or list of standard names. PDF version is used if provided in the list, but otherwise inferred from the standard.
55+
56+
If you specify a PDF standard, Quarto first instructs LaTeX or Typst to use the standard when producing the PDF, and then validates the output PDF against the standard using veraPDF, an open-source PDF validation tool. If veraPDF is not installed, you'll get a warning but still receive a PDF -- it just won't be validated.
57+
58+
::: {.callout-note}
59+
## Installing veraPDF
60+
61+
To install veraPDF, you'll first need Java, then run:
62+
63+
```{.bash filename="Terminal"}
64+
quarto install verapdf
65+
```
66+
67+
:::
68+
69+
When a document passes validation, you'll see output like:
70+
71+
```
72+
[verapdf]: Validating my-document.pdf against PDF/UA-2... PASSED
73+
```
74+
75+
## Creating accessible PDFs
76+
77+
Quarto's Markdown-based workflow handles many accessibility requirements automatically:
78+
79+
* Document metadata (title, author, date, language) flows into the PDF's built-in metadata fields.
80+
* The semantic structure of Markdown satisfies PDF tagging requirements. For Typst this is always enabled; for LaTeX it is enabled when you specify a standard that requires it.
81+
* Alt text for images is carried through to the PDF for screen readers.
82+
83+
But you do need to make sure your document has:
84+
85+
* A **title** in the YAML front matter.
86+
* **Alt text for every image**, specified with `fig-alt`. See [Figures](https://{{< meta prerelease-link-subdomain >}}quarto.org/docs/authoring/figures.html#alt-text) for details.
87+
88+
See the [LaTeX](https://{{< meta prerelease-link-subdomain >}}quarto.org/docs/output-formats/pdf-basics.html#accessibility-requirements) and [Typst](https://{{< meta prerelease-link-subdomain >}}quarto.org/docs/output-formats/typst.html#accessibility-requirements) documentation for more details.
89+
90+
## If your document fails validation
91+
92+
LaTeX does not perform validation during PDF generation, so if veraPDF validation fails, that's a warning, and you still get a partially-accessible PDF as long as you use `pdf-standard: ua-2`.
93+
94+
Typst fails and does not produce a PDF if its built-in validation fails during PDF generation. However, in Typst all accessibility features are on by default, so you can generate a partially-accessible PDF by rendering without `pdf-standard`.
95+
96+
## Current limitations
97+
98+
We ran our test suite -- 188 LaTeX examples and 317 Typst examples -- to find where Quarto PDFs do not yet pass UA-1 or UA-2, and where users will need to change their documents.
99+
100+
### LaTeX
101+
102+
Margin content is the biggest structural blocker. If you use `.column-margin` divs, `cap-location: margin`, `reference-location: margin`, or `citation-location: margin`, the resulting PDF will not pass UA-2. The underlying `sidenotes` and `marginnote` LaTeX packages [do not cooperate with PDF tagging](https://github.com/quarto-dev/quarto-cli/issues/14103).
103+
104+
(Margin content does work with Typst and passes UA-1 -- see [Typst Article Layout](https://{{< meta prerelease-link-subdomain >}}quarto.org/docs/output-formats/typst.html#article-layout).)
105+
106+
There are smaller upstream issues in Pandoc, LaTeX, and LaTeX packages, [documented here](https://github.com/quarto-dev/quarto-cli/pull/14097#issuecomment-3947653207).
107+
108+
### Typst
109+
110+
In our tests, Typst catches every UA-1 violation, and fails to generate the PDF. veraPDF did not detect any violation that Typst did not.
111+
112+
Typst also seems to do a very good job of generating UA-1 compliant output by default -- almost all errors were due to missing titles or missing alt text.
113+
114+
However, we did discover that [Typst books](https://{{< meta prerelease-link-subdomain >}}quarto.org/docs/books/book-output.html#typst-output) are not yet compliant. There is a [structural problem with the Typst orange-book package](https://github.com/flavio20002/typst-orange-template/issues/38) and we'll work with the maintainers to correct it.
115+
116+
## Conclusion
117+
118+
Although Typst currently targets an the earlier UA-1 standard, today it seems to offer better PDF accessibility than LaTeX.
119+
120+
We expect PDF accessibility support to improve through the LaTeX ecosystem throughout 2026 as awareness of UA-2 and the new regulations spreads.
121+
122+
If you run into accessibility issues with PDF output, please search the [Quarto discussions](https://github.com/orgs/quarto-dev/discussions) and open a new one with the `accessibility` label for any issues you discover.

‎docs/blog/posts/2026-03-05-pdf-accessibility-and-standards/thumbnail.png‎

40.7 KB
Loading

‎docs/blog/posts/_quarto-1.9-feature.qmd‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
::: callout-note
2+
## Pre-release Feature
3+
4+
This feature is new in the upcoming Quarto 1.9 release. To use the feature now, you'll need to [download and install](/docs/download/prerelease.qmd) the Quarto pre-release.
5+
:::

0 commit comments

Comments
 (0)