Support alt text for inline math

[gordonwoodhull]

Pandoc does not allow alt text for inline equations, at the AST level.

This may be a temporary issue because UA-2 does much smarter MathML interpretation of equations, where you no longer need alt text.

But there will be a transitionary period, as seen in

• https://github.com/orgs/quarto-dev/discussions/14119

where some tools and readers may still need UA-1 alt text for equations, even when UA-2 mathml is available.

LaTeX implements UA-2, and it's highly likely that Typst will implement UA-2 later this year.

q2 support free-floating attribute blocks, so this is directly fixable with no new syntax there. For Pandoc we'd need to invent a new syntax. ☹️

Description

Quarto currently supports alt text for display math equations via {#eq-label alt="..."} (added in #13889), but there is no mechanism for adding alt text to inline math expressions. This causes PDF/UA-1 validation failures when documents contain inline math like $a$, $f(x)$, or $a^2 + b^2 = c^2$ in Typst output.

Typst's PDF/UA-1 mode requires every math.equation element (including inline) to have an alt parameter. Without a way to specify this from Quarto markdown, any document with inline math will fail UA-1 validation.

Current state

• Display math with labels: ✅ Supported via {#eq-label alt="..."}
• Display math without labels: ❌ No mechanism
• Inline math: ❌ No mechanism

Steps to Reproduce

---
format:
  typst:
    pdf-standard: ua-1
---

For a right triangle with legs $a$ and $b$ and hypotenuse $c$: $a^2 + b^2 = c^2$

Each inline math expression produces: error: PDF/UA-1 error: missing alt text

Impact

In testing Quarto book extensions (bookly, ilm, wonderous-book) with pdf-standard: ua-1, after fixing all image and display equation alt text, the only remaining errors are inline math — 30 errors per project, all from theorem/definition content containing inline variables and formulas.

Possible approaches

1. Span syntax: Allow [$a$]{alt="a"} to propagate the alt attribute to the generated Typst math.equation
2. Auto-generation: Automatically generate alt text from the math source (e.g., $a$ → alt: "a", $a^2 + b^2 = c^2$ → alt: "a^2 + b^2 = c^2") — the LaTeX/Typst source is often a reasonable alt text for simple expressions
3. Global show rule: Emit a Typst show rule like show math.equation: set math.equation(alt: ...) if the document uses pdf-standard: ua-1 — though Typst currently doesn't support setting alt via show rules

Note: Typst plans to support MathML-based accessibility in PDF 2.0 which would make manual alt text unnecessary, but for PDF/UA-1 the alt parameter is the only option.

[andrewheiss]

In the meantime (since my university is enforcing accessibility requirements within the next few weeks), I claude coded a little Lua filter to automatically add the LaTeX source to alt and it's working!

-- math-alt.lua
-- For Typst/PDF-UA-1 output: adds alt text to math equations using the
-- LaTeX source as the text alternative. Uses pandoc.write to get the
-- already-converted Typst math syntax, then wraps it so Typst can attach
-- the alt attribute.

function Math(el)
  if FORMAT ~= "typst" then return nil end

  -- Get the Typst-converted math string via pandoc's own Typst writer
  local tmp = pandoc.Pandoc({ pandoc.Para({ el }) })
  local typst = pandoc.write(tmp, "typst"):match("^%s*(.-)%s*$")

  -- Escape the LaTeX source for use as a Typst string literal
  local alt = el.text
    :gsub("\\", "\\\\")
    :gsub('"', '\\"')
    :gsub("\n", " ")

  local is_block = tostring(el.mathtype == "DisplayMath")

  -- Extract body from a temp equation, then recreate with alt text.
  -- Can't use ..it.fields() directly in a show rule because Typst doesn't
  -- expose `alt` as a filterable/checkable field, causing infinite recursion.
  local code = string.format(
    '#{ let _q = %s; math.equation(_q.body, alt: "%s", block: %s) }',
    typst, alt, is_block
  )

  return pandoc.RawInline("typst", code)
end

In this example Quarto file:

---
title: "Test thing"
author: "Andrew Heiss"
date: 2026-03-09
filters:
  - math-alt.lua
format:
  typst:
    keep-typ: true
    pdf-standard: ua-1
---

Here's some inline math $R^2$ and some block math:

$$
y = \beta_0 + \beta_1 x_1 + \varepsilon
$$

…the filter generates typst like this:

Here's some inline math #{ let _q = $R^2$; math.equation(_q.body, alt: "R^2", block: false) } and some block math:

#{ let _q = $ y = beta_0 + beta_1 x_1 + epsilon $; math.equation(_q.body, alt: " y = \\beta_0 + \\beta_1 x_1 + \\varepsilon ", block: true) }

…and rendering to Typst results in this:

❯ quarto render testing.qmd
  
[typst]: Compiling basic.typ to basic.pdf...DONE

[verapdf]: Validating basic.pdf against PDF/UA1...PASSED

Output created: testing.pdf

[mcanouil]

@andrewheiss DisplayMath equation has alt-text support. Only inline does not.
I'm not sure filling alt with the equation is an accessibility move. it's very similar to filling "alt" for all figures with "Image" (that's what GitHub does...)

[andrewheiss]

I was just going with @gordonwoodhull's option 2 above: "the LaTeX/Typst source is often a reasonable alt text for simple expressions", since the alt text for basic inline things like $x + 1$ can reasonably be "x + 1", and like 99% of my inline stuff in this course is just super basic expressions

But having the option 1 span syntax [$a$]{alt="a"} would probably be the best actual long term solution (this little filter is just because I have to get all PDFs perfectly accessible in the next week and needed some sort of stopgap :) )

[mcanouil]

I have that kind of workaround filter somewhere from when I was experimenting to add alt text support to equations.
I'll post here once I've found the code again.

[mcanouil]

Here it is, to merge parent span/div "alt" attribute.

---
title: "Alternative text"
format:
  typst:
    keep-typ: true
    pdf-standard: ua-1
filters:
  - typst-math-alt.lua
---

Here's some inline math [$R^2$]{alt="The coefficient of determination"} and some block math:

$$
y = \beta_0 + \beta_1 x_1 + \varepsilon
$$ {#eq-one alt="A simple linear regression model"}


::: {alt="A simple linear regression model"}

$$
y = \beta_0 + \beta_1 x_1 + \varepsilon
$$

:::

--- typst-math-alt - Filter
--- @module typst-math-alt.lua
--- @license MIT
--- @copyright 2026 Mickaël Canouil
--- @author Mickaël Canouil
--- @version 0.1.0
--- @brief Emit #math.equation(alt: ...) for Math elements wrapped in a
---   Span or Div that carries an alt attribute.
--- @description Quarto already generates math.equation(alt: ...) for
---   display equations with a cross-reference label, but equations that
---   only have {alt="..."} (no label) lose their alt text in Typst output.
---   This filter intercepts Span and Div elements with an alt attribute
---   that contain a Math element and emits explicit Typst raw content.

local function escape_typst_string(s)
  return s:gsub('\\', '\\\\'):gsub('"', '\\"')
end

local function math_to_typst(math_el)
  local doc = pandoc.Pandoc({ pandoc.Para({ math_el }) })
  local raw = pandoc.write(doc, "typst")
  return raw:match("^%s*(.-)%s*$")
end

function Span(el)
  if not quarto.doc.is_format("typst") then
    return nil
  end
  local alt = el.attributes["alt"]
  if alt == nil then
    return nil
  end

  local math_el = nil
  el:walk({
    Math = function(m)
      math_el = m
    end,
  })
  if math_el == nil then
    return nil
  end

  local typst_math = math_to_typst(math_el)
  local escaped_alt = escape_typst_string(alt)

  if math_el.mathtype == "DisplayMath" then
    return pandoc.RawBlock(
      "typst",
      '#math.equation(block: true, alt: "' .. escaped_alt .. '", [ ' .. typst_math .. " ])"
    )
  end
  return pandoc.RawInline(
    "typst",
    '#math.equation(alt: "' .. escaped_alt .. '", ' .. typst_math .. ")"
  )
end

function Div(el)
  if not quarto.doc.is_format("typst") then
    return nil
  end
  local alt = el.attributes["alt"]
  if alt == nil then
    return nil
  end

  local math_el = nil
  el:walk({
    Math = function(m)
      math_el = m
    end,
  })
  if math_el == nil then
    return nil
  end

  local typst_math = math_to_typst(math_el)
  local escaped_alt = escape_typst_string(alt)

  if math_el.mathtype == "DisplayMath" then
    return pandoc.RawBlock(
      "typst",
      '#math.equation(block: true, alt: "' .. escaped_alt .. '", [ ' .. typst_math .. " ])"
    )
  end
  return pandoc.RawInline(
    "typst",
    '#math.equation(alt: "' .. escaped_alt .. '", ' .. typst_math .. ")"
  )
end

[cscheid]

Just to start setting Q2 expectations, the syntax

[$a$]{alt="a"}

isn't far from the Q2 syntax, which allows $a${alt="a"} directly. Quarto 2 (and pampa, the pure-Rust pandoc` "port" in the q2 code base) currently desugars to the following Pandoc native structure:

$ pampa -f qmd -t native -i test-q2-eq-attr.qmd
Warning [Q-7-1]: Missing Newline at End of File
File `test-q2-eq-attr.qmd` does not end with a newline
ℹ A newline will be added automatically

[ Para [Span ( "" , ["quarto-math-with-attribute"] , [("alt", "foo")] ) [Math InlineMath "a"]] ]