Fix caption used as fallback alt text in PDF/UA

[gordonwoodhull]

Summary

Removes the anti-pattern where figure captions are copied into image alt text for PDF/UA compliance. Captions describe a figure's significance in context; alt text describes what the image looks like. Using one as the other is an accessibility anti-pattern that merely silences validators without helping screen reader users.

This was introduced in the Jan 2026 PDF/UA work (commits a867c3c24 and ba75b374f) to satisfy PDF/UA validators, which require every <Figure> structure element to have an /Alt string.

Fixes #14107

What changed

LaTeX (latex.lua): Removed 3 caption-as-alt blocks that copied image.caption into image.attributes["alt"] before clearing the caption for separate rendering.

Typst (pandoc3_figure.lua, floatreftarget.lua, typst.lua): Used a marker attribute (_quarto_no_caption_alt) to prevent the caption-as-alt fallback for figure images, while preserving it for inline images where image.caption IS the standard markdown alt text (![alt text](img.svg) in running text).

The distinction matters because of how Pandoc 3 represents alt text in its AST.

Pandoc 3 AST analysis

In Pandoc 3, {alt="text"} on an image does not set image.attributes["alt"] — it replaces image.caption with the alt value. The ![visible caption] text moves to figure.caption.long, while image.caption becomes the alt text. This means image.caption serves double duty:

• Inline images: image.caption IS the alt text (the ![...] content is alt by the HTML spec)
• Figure images: image.caption is a copy of the visible caption (unless overridden by {alt="..."})

To distinguish these cases, we compare image.caption to the figure's visible caption (figure.caption.long or float.caption_long). If they match, no explicit alt was provided — we set _quarto_no_caption_alt to suppress the fallback. If they differ, {alt="..."} was used and image.caption IS the explicit alt text.

This is the same heuristic Pandoc's own Markdown writer uses (confirmed via Pandoc source — it compares image alt to figure caption to decide whether to emit {alt="..."}). Pandoc itself acknowledges the ambiguity: the AST cannot distinguish "caption that happens to match alt" from "no explicit alt provided." The recommended workaround is Quarto's fig-alt attribute, which flows through a separate, unambiguous path.

How fig-alt vs alt work

• {alt="text"}: Pandoc replaces image.caption, no separate attribute. Works but ambiguous when caption and alt are intentionally identical.
• {fig-alt="text"}: Quarto stores as image.attributes["fig-alt"], propagated explicitly to \includegraphics[alt=...] (LaTeX) or image(alt: "...") (Typst). Always unambiguous. This is the recommended approach.

Test plan

• caption-not-alt-ua.qmd — verifies caption is NOT copied to \includegraphics[alt=] and that Quarto warns about missing alt text
• typst-image-alt-text.qmd — TC1 moved to must-not-match; TC8 added for fig-alt
• ua-image-alt-text.qmd — now uses explicit fig-alt
• All 39 pdf-standard tests pass

[gordonwoodhull]

Second commit: Fix tagpdf warning parsing and document UA-2 structural issue

The second commit (32d1172ab) addresses two things discovered while testing:

1. tagpdf warning regex fix (parse-error.ts)

The regex that parses tagpdf's "Alternative text for graphic is missing" warning assumed the filename and instead. appeared on a single (tagpdf) continuation line. When filenames are long, tagpdf wraps across multiple lines:

Package tagpdf Warning: Alternative text for graphic is missing.
(tagpdf)                Using 'caption-not-alt-ua_files/mediabag/penrose.pdf'
(tagpdf)                instead.

Fixed the regex to allow an optional (tagpdf) line break before instead.. Also updated the warning message to recommend fig-alt instead of the old ![alt text](image.png) advice (which was itself the caption-as-alt anti-pattern).

2. UA-2 structural issue with unlabeled captioned figures (ua2-unlabeled-figure-caption.qmd)

Discovered that unlabeled captioned figures (![caption](img.svg) without {#fig-label}) produce invalid UA-2 structure. These go through pandoc3_figure.lua → latexImageFigure() → bare \begin{figure}[H], and tagpdf places <Caption> as a sibling of <Figure> directly under <Document>:

/Document
  /Caption    ← UA-2 violation: must be inside a grouping element
  /Figure     ← orphaned from its caption

Labeled figures ({#fig-label}) go through FloatRefTarget, which wraps in a \Div that provides the grouping context:

/Document
  /Div
    /Caption  ← properly nested ✓
    /Figure

This is a pre-existing LaTeX/tagpdf limitation, not caused by our changes. Added ua2-unlabeled-figure-caption.qmd to document it with the expected verapdf validation warning, and updated caption-not-alt-ua.qmd to use a labeled figure to avoid conflating the two issues.

[posit-snyk-bot]

✅ Snyk checks have passed. No issues have been found so far.

Status	Scanner	Critical	High	Medium	Low	Total (0)
✅	Open Source Security	0	0	0	0	0 issues
✅	Licenses	0	0	0	0	0 issues

💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse.