Fix: caption should not be used as fallback alt text

Remove the caption-as-alt fallback introduced in the PDF/UA compliance
work (a867c3c, ba75b37). Using captions as alt text is an
accessibility anti-pattern — captions describe a figure's significance
in context while alt text describes what the image looks like.

LaTeX: remove 3 caption-as-alt blocks in latex.lua, and add fig-alt to
alt conversion in pandoc3_figure.lua for Pandoc 3 Figures without
cross-ref labels.

Typst: mark figure images with _quarto_no_caption_alt so that the
caption-as-alt fallback in typst.lua only fires for inline images
(where image.caption IS the standard markdown alt text).

Key insight: In Pandoc 3, {alt="text"} replaces the Image's caption
content rather than populating image.attributes["alt"]. So
image.caption serves double duty as both visible caption and alt text
override. We distinguish the two cases by comparing image.caption to
figure.caption — when they match, the caption was NOT overridden (the
bug case we suppress); when they differ, an explicit {alt="..."} was
provided (which we preserve). This is the same heuristic Pandoc's own
Markdown writer uses when round-tripping Figures.

Explicit fig-alt (Quarto's dedicated attribute) flows through a
completely separate path and always works unambiguously.

Fixes #14107

Author: gordonwoodhull

src/resources/filters/customnodes/floatreftarget.lua

@@ -978,6 +978,22 @@ end, function(float)
   local kind = "quarto-float-" .. ref
   local supplement = titleString(ref, info.name)
 
+  -- For figures: mark images so typst.lua won't use caption-as-alt fallback
+  -- when caption IS the visible figure caption (not an explicit alt override).
+  -- In Pandoc 3, {alt="text"} replaces image.caption with the alt value,
+  -- so image.caption != float.caption means an explicit alt was provided.
+  if ref == "fig" then
+    local float_caption_text = pandoc.utils.stringify(float.caption_long or {})
+    float.content = _quarto.ast.walk(float.content, {
+      Image = function(img)
+        if pandoc.utils.stringify(img.caption) == float_caption_text then
+          img.attributes["_quarto_no_caption_alt"] = "true"
+        end
+        return img
+      end
+    })
+  end
+
   -- Inject show rule to left-align listing figures (only once per document)
   -- This overrides any template centering for listing-kind figures
   -- https://github.com/quarto-dev/quarto-cli/issues/9724

src/resources/filters/layout/latex.lua

@@ -332,10 +332,6 @@ function latexCell(cell, vAlign, endOfRow, endOfTable)
     -- see if it's a captioned figure
     if image and #image.caption > 0 then
       caption = image.caption:clone()
-      -- preserve caption as alt attribute for PDF accessibility before clearing
-      if not image.attributes["alt"] then
-        image.attributes["alt"] = pandoc.utils.stringify(image.caption)
-      end
       tclear(image.caption)
     elseif tbl then
       caption = pandoc.utils.blocks_to_inlines(tbl.caption.long)
@@ -384,10 +380,6 @@ function latexCell(cell, vAlign, endOfRow, endOfTable)
     if image and #image.caption > 0 then
       local caption = image.caption:clone()
       markupLatexCaption(cell, caption)
-      -- preserve caption as alt attribute for PDF accessibility before clearing
-      if not image.attributes["alt"] then
-        image.attributes["alt"] = pandoc.utils.stringify(image.caption)
-      end
       tclear(image.caption)
       content:insert(pandoc.RawBlock("latex", "\\raisebox{-\\height}{"))
       content:insert(pandoc.Para(image))
@@ -669,10 +661,6 @@ function latexImageFigure(image)
 
     -- make a copy of the caption and clear it
     local caption = image.caption:clone()
-    -- preserve caption as alt attribute for PDF accessibility before clearing
-    if #image.caption > 0 and not image.attributes["alt"] then
-      image.attributes["alt"] = pandoc.utils.stringify(image.caption)
-    end
     tclear(image.caption)
 
     -- get align

src/resources/filters/layout/pandoc3_figure.lua

@@ -146,6 +146,13 @@ function render_pandoc3_figure()
       for k, v in pairs(figure.attributes) do
         image.attributes[k] = v
       end
+      -- Convert fig-alt to alt for LaTeX \includegraphics[alt=...]
+      if image.attributes[kFigAlt] then
+        if not image.attributes["alt"] then
+          image.attributes["alt"] = image.attributes[kFigAlt]
+        end
+        image.attributes[kFigAlt] = nil
+      end
       if subfig then
         image.attributes['quarto-caption-env'] = 'subcaption'
       end
@@ -170,6 +177,26 @@ function render_pandoc3_figure()
     return {
       traverse = "topdown",
       Figure = function(figure)
+        -- For figure images: prevent caption-as-alt fallback when caption IS the
+        -- visible figure caption (not an explicit alt override via {alt="..."}).
+        -- In Pandoc 3, {alt="text"} replaces image.caption with the alt value,
+        -- so image.caption != figure.caption means an explicit alt was provided.
+        -- Also propagate fig-alt from figure to image for accessibility.
+        local figure_caption_text = pandoc.utils.stringify(figure.caption.long)
+        local fig_alt = figure.attributes[kFigAlt]
+        for _, block in ipairs(figure.content) do
+          if block.t == "Plain" or block.t == "Para" then
+            for _, inline in ipairs(block.content) do
+              if inline.t == "Image" then
+                if fig_alt then
+                  inline.attributes[kFigAlt] = fig_alt
+                elseif pandoc.utils.stringify(inline.caption) == figure_caption_text then
+                  inline.attributes["_quarto_no_caption_alt"] = "true"
+                end
+              end
+            end
+          end
+        end
         return make_typst_figure({
           content = figure.content[1],
           caption = figure.caption.long[1],

src/resources/filters/quarto-post/typst.lua

@@ -232,7 +232,11 @@ function render_typst_fixups()
       if alt_text then
         image.attributes[kFigAlt] = nil
       end
-      if (alt_text == nil or alt_text == "") and #image.caption > 0 then
+      -- Use caption as alt only for inline images (not figures)
+      -- Figure images are marked with _quarto_no_caption_alt by layout filters
+      local no_caption_alt = image.attributes["_quarto_no_caption_alt"]
+      image.attributes["_quarto_no_caption_alt"] = nil
+      if (alt_text == nil or alt_text == "") and #image.caption > 0 and not no_caption_alt then
         alt_text = pandoc.utils.stringify(image.caption)
       end
 

tests/docs/smoke-all/pdf-standard/caption-not-alt-ua.qmd

@@ -0,0 +1,32 @@
+---
+title: "Caption should not be used as fallback alt text"
+lang: en
+format:
+  pdf:
+    pdf-standard: ua-2
+    keep-tex: true
+  typst:
+    pdf-standard: ua-1
+    keep-typ: true
+_quarto:
+  tests:
+    run:
+      # verapdf validation not available on Windows CI
+      not_os: windows
+    pdf:
+      noErrors: default
+      ensureLatexFileRegexMatches:
+        - ['\\DocumentMetadata\{', 'pdfstandard=\{ua-2\}', 'tagging=on']
+        - # Caption must NOT appear as alt text on \includegraphics
+          ['includegraphics\[.*alt=']
+    typst:
+      # Typst's own PDF/UA enforcement errors on missing alt
+      shouldError: default
+---
+
+# Caption is not alt text
+
+A figure with a caption but no explicit `fig-alt`.
+The caption should NOT be copied into alt text.
+
+![This is a caption, not alt text](penrose.svg)

tests/docs/smoke-all/pdf-standard/tc8-fig-alt.svg

@@ -9,15 +9,18 @@ _quarto:
       noErrors: default
       ensureTypstFileRegexMatches:
         - # Patterns that MUST be found - alt text in image() calls
-          - 'image\("tc1-figure\.svg",\s*alt:\s*"TC1 figure caption as alt'
           - 'image\("tc2-inline\.svg",\s*alt:\s*"TC2 inline image'
           - 'image\("tc3-explicit\.svg",\s*alt:\s*"TC3 explicit alt attribute'
           - 'image\("tc4-dimensions\.svg",\s*alt:\s*"TC4 with dimensions",\s*height:\s*1in,\s*width:\s*1in'
           - 'image\("tc5-quotes\.svg",\s*alt:\s*"TC5 with \\"escaped\\" quotes'
           - 'image\("tc6-backslash\.svg",\s*alt:\s*"TC6 backslash C:\\\\path'
           # TC7 should have the image but without alt parameter
           - 'image\("tc7-no-alt\.svg"\)'
+          # TC8: Explicit fig-alt should produce alt text
+          - 'image\("tc8-fig-alt\.svg",\s*alt:\s*"TC8 explicit fig-alt'
         - # Patterns that must NOT be found
+          # TC1 figure caption should NOT be used as alt text
+          - 'tc1-figure\.svg.*alt:.*TC1 figure caption'
           # TC7 with no caption/alt should NOT have alt parameter
           - 'tc7-no-alt\.svg.*alt:'
 ---
@@ -55,3 +58,7 @@ Here is ![TC4 with dimensions](tc4-dimensions.svg){width=1in height=1in} inline.
 This image has no caption and no alt attribute.
 
 ![](tc7-no-alt.svg)
+
+## TC8: Explicit fig-alt on a figure
+
+![TC8 visible caption](tc8-fig-alt.svg){fig-alt="TC8 explicit fig-alt description"}

tests/docs/smoke-all/pdf-standard/typst-image-alt-text.qmd

@@ -32,4 +32,4 @@ _quarto:
 
 This image has alt text which should be passed through for PDF/UA compliance.
 
-![Test image description](penrose.svg)
+![Test image description](penrose.svg){fig-alt="A Penrose tiling pattern"}