diff --git a/docs/blog/posts/2026-02-xx-pdf-accessibility-and-standards/index.qmd b/docs/blog/posts/2026-02-xx-pdf-accessibility-and-standards/index.qmd new file mode 100644 index 0000000000..051798cbaf --- /dev/null +++ b/docs/blog/posts/2026-02-xx-pdf-accessibility-and-standards/index.qmd @@ -0,0 +1,122 @@ +--- +title: PDF Accessibility and Standards +description: | + Quarto 1.9 brings PDF accessibility and standards support, building on new tagging features in LaTeX and Typst. +author: Gordon Woodhull +date: "2026-02-xx" +image: verapdf.jpg +image-alt: "veraPDF logo" +draft: true +quarto-root: https://prerelease.quarto.org +--- + +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). + +Quarto 1.9 brings this support to you as a Quarto user. + +## What PDF Standards Do + +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. + +Both standards instruct the PDF renderer to provide screen readers: + +* The semantic structure of the text (title, heading, paragraph, figure, etc) +* The natural reading order +* Spatial coordinates for highlighting and assistive navigation +* Required metadata such as title and language + +## How to enable a PDF Standard in Quarto + +In Quarto 1.9, specify a PDF standard for your document or project with `pdf-standard` + +::::: {layout-ncol=2} +:::: {} +**PDF (LaTeX)** + +```yaml +format: + pdf: + pdf-standard: ua-2 +``` +:::: + +:::: {} +**Typst** + +```yaml +format: + typst: + pdf-standard: ua-1 +``` +:::: +::::: + +`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. + +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. + +::: {.callout-note} +## Installing veraPDF + +To install veraPDF, you'll first need Java, then run: + +```{.bash filename="Terminal"} +quarto install verapdf +``` + +::: + +When a document passes validation, you'll see output like: + +``` +[verapdf]: Validating my-document.pdf against PDF/UA-2... PASSED +``` + +## Creating accessible PDFs + +Quarto's Markdown-based workflow handles many accessibility requirements automatically: + +* Document metadata (title, author, date, language) flows into the PDF's built-in metadata fields. +* 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. +* Alt text for images is carried through to the PDF for screen readers. + +But you do need to make sure your document has: + +* A **title** in the YAML front matter. +* **Alt text for every image**, specified with `fig-alt`. See [Figures]({{< meta quarto-root >}}/docs/authoring/figures.html#alt-text) for details. + +See the [LaTeX]({{< meta quarto-root >}}/docs/output-formats/pdf-basics.html#accessibility-requirements) and [Typst]({{< meta quarto-root >}}/docs/output-formats/typst.html#accessibility-requirements) documentation for more details. + +## If your document fails validation + +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`. + +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`. + +## Current limitations + +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. + +### LaTeX + +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). + +(Margin content does work with Typst and passes UA-1 -- see [Typst Article Layout]({{< meta quarto-root >}}/docs/output-formats/typst.html#article-layout).) + +There are smaller upstream issues in Pandoc, LaTeX, and LaTeX packages, [documented here](https://github.com/quarto-dev/quarto-cli/pull/14097#issuecomment-3947653207). + +### Typst + +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. + +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. + +However, we did discover that [Typst Books]({{< meta quarto-root >}}/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. + +## Conclusion + +Although Typst currently targets an the earlier UA-1 standard, today it seems to offer better PDF accessibility than LaTeX. + +We expect PDF accessibility support to improve through the LaTeX ecosystem throughout 2026 as awareness of UA-2 and the new regulations spreads. + +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. diff --git a/docs/blog/posts/2026-02-xx-pdf-accessibility-and-standards/verapdf.jpg b/docs/blog/posts/2026-02-xx-pdf-accessibility-and-standards/verapdf.jpg new file mode 100644 index 0000000000..c9bc1bc1af Binary files /dev/null and b/docs/blog/posts/2026-02-xx-pdf-accessibility-and-standards/verapdf.jpg differ