Add Typst image alt text for PDF/UA accessibility

Workaround for Pandoc not passing alt text to Typst image() calls.
When an image has alt text (from caption or fig-alt), emits raw Typst
with image(..., alt: "...") for accessibility compliance.

Temporary fix until pandoc#11394 is merged upstream.

Closes #13868

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: gordonwoodhull

news/changelog-1.9.md

@@ -42,6 +42,7 @@ All changes included in 1.9:
 - ([#13589](https://github.com/quarto-dev/quarto-cli/issues/13589)): Fix callouts with invalid ID prefixes crashing with "attempt to index a nil value". Callouts with unknown reference types now render as non-crossreferenceable callouts with a warning, ignoring the invalid ID.
 - ([#13602](https://github.com/quarto-dev/quarto-cli/issues/13602)): Fix support for multiple files set in `bibliography` field in `biblio.typ` template partial.
 - ([#13775](https://github.com/quarto-dev/quarto-cli/issues/13775)): Fix brand fonts not being applied when using `citeproc: true` with Typst format. Format detection now properly handles Pandoc format variants like `typst-citations`.
+- ([#13868](https://github.com/quarto-dev/quarto-cli/issues/13868)): Add image alt text support for PDF/UA accessibility. Alt text from markdown captions and explicit `alt` attributes is now passed to Typst's `image()` function. (Temporary workaround until [jgm/pandoc#11394](https://github.com/jgm/pandoc/pull/11394) is merged.)
 - ([#13249](https://github.com/quarto-dev/quarto-cli/pull/13249)): Update to Pandoc's Typst template following Pandoc 3.8.3 and Typst 0.14.2 support:
   - Code syntax highlighting now uses Skylighting by default.
   - New template variables `mathfont`, `codefont`, and `linestretch` for font and line spacing customization.

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

@@ -94,6 +94,48 @@ function render_typst_fixups()
       if image.attributes["width"] ~= nil and type(width_as_number) == "number" then
         image.attributes["width"] = tostring(image.attributes["width"] / PANDOC_WRITER_OPTIONS.dpi) .. "in"
       end
+
+      -- Workaround for Pandoc not passing alt text to Typst image() calls
+      -- See: https://github.com/jgm/pandoc/issues/XXXX (TODO: file upstream)
+      local alt_text = image.attributes["alt"]
+      if (alt_text == nil or alt_text == "") and #image.caption > 0 then
+        alt_text = pandoc.utils.stringify(image.caption)
+      end
+
+      if alt_text and #alt_text > 0 then
+        -- When returning RawInline instead of Image, Pandoc won't write mediabag
+        -- entries to disk, so we must do it explicitly
+        local src = image.src
+        local mediabagPath = _quarto.modules.mediabag.write_mediabag_entry(src)
+        if mediabagPath then
+          src = mediabagPath
+        end
+
+        -- Build image() parameters
+        local params = {}
+
+        -- Source path (escape backslashes for Windows paths)
+        src = src:gsub('\\', '\\\\')
+        table.insert(params, '"' .. src .. '"')
+
+        -- Alt text second (escape backslashes and quotes)
+        local escaped_alt = alt_text:gsub('\\', '\\\\'):gsub('"', '\\"')
+        table.insert(params, 'alt: "' .. escaped_alt .. '"')
+
+        -- Height if present
+        if image.attributes["height"] then
+          table.insert(params, 'height: ' .. image.attributes["height"])
+        end
+
+        -- Width if present
+        if image.attributes["width"] then
+          table.insert(params, 'width: ' .. image.attributes["width"])
+        end
+
+        -- Use #box() wrapper for inline compatibility
+        return pandoc.RawInline("typst", "#box(image(" .. table.concat(params, ", ") .. "))")
+      end
+
       return image
     end,
     Div = function(div)

tests/docs/smoke-all/crossrefs/float/typst/typst-float-4.qmd

@@ -6,10 +6,11 @@ _quarto:
   tests:
     typst:
       ensureTypstFileRegexMatches:
-        - 
+        -
           - "#ref\\(<tbl-foo>, supplement: \\[Table\\]\\)"
           - "#ref\\(<fig-foo>, supplement: \\[Figure\\]\\)"
-          - "#link\\(\"https://www.example.com/\"\\)\\[#.*image\\(\"img/surus.jpg\"\\)\\)"
+          # Images with captions now include alt text for accessibility
+          - '#link\("https://www\.example\.com/"\)\[#box\(image\("img/surus\.jpg", alt:'
 ---
 
 This tests:

tests/docs/smoke-all/pdf-standard/alt-test.qmd

@@ -0,0 +1,8 @@
+---
+title: "Alt text test"
+pdf-standard: ua-1
+keep-tex: true
+---
+
+![This is the alt text](penrose.svg)
+