quarto-dev / quarto-dev/quarto-cli
Epic: `fig-alt` not propagated to output across multiple formats
Nobody has claimed this yet.
- Dominant language
- JavaScript
- Stars
- 6k
- Forks
- 458
- Avg merge
- 1d 9h
- Merged PRs (30d)
- 41
Description
fig-alt is Quarto's attribute for providing alternative text on images, distinct from
the visible caption. It needs to be converted to each output format's native alt text
mechanism by the Lua filter pipeline before Pandoc writes the output.
This conversion was implemented for HTML first, then extended for PDF/Typst in 1.9, but
markdown formats (hugo-md, gfm, commonmark) and docx have no conversion at all. The
result is that fig-alt either becomes a non-functional data-fig-alt HTML attribute
in markdown output, or is silently dropped in docx.
How it should work
When fig-alt is set on an image:
- The output should contain alt text derived from
fig-alt, using the format's native mechanism fig-altshould override caption-derived alt text when both are presentfig-altshould not appear asdata-fig-altor any other non-functional attribute
Current state by format
Two code paths matter: simple images (no cross-ref, no #fig- id) and cross-referenced
figures (FloatRefTarget).
| Format | Simple image | FloatRefTarget | Issue |
|---|---|---|---|
| HTML | works | works | — |
| LaTeX | lost (no caption → no Figure node) | works | #14315 |
| Typst | works | lost with fig-align + no caption |
#14187 |
| docx | lost | works | #5514 |
| hugo-md | data-fig-alt |
alt discarded by renderer |
#14344 |
| gfm | data-fig-alt |
uncertain | #12456 |
Root cause
fig-alt conversion is implemented per-format in scattered locations:
- HTML simple images:
quarto-post/html.luaImage handler - LaTeX Figure nodes:
layout/pandoc3_figure.lua - Typst:
quarto-post/typst.luaImage handler - FloatRefTarget (all non-HTML):
quarto-pre/figures.luasetsimage.attributes["alt"]
Markdown formats have no conversion at all. For markdown output with raw_html enabled
(hugo-md, gfm, md), Pandoc falls back to <img> HTML for images with custom attributes.
Since fig-alt is not a standard HTML attribute, Pandoc prefixes it with data- →
data-fig-alt.
Documentation gap
The authoring guide presents
fig-alt without format caveats but only shows HTML output examples. The YAML cell
reference schema (formats field for fig-alt) explicitly lists only HTML-family
formats. The 1.9 PDF/Typst accessibility support is not yet reflected in the schema.
No documentation warns that fig-alt is silently dropped in gfm, hugo-md, docx, or
other markdown formats.
Additional related issues
- #11478 —
fig-capbecomes alt text instead of figcaption in hugo-md - #3873, #9003 —
fig-altnot supported for mermaid/diagrams - #14338 — PDF validation should fail with no alt text
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reading the listed handlers in quarto-post/html.lua, quarto-post/typst.lua, layout/pandoc3_figure.lua, and quarto-pre/figures.lua, then trace markdown and docx output for simple images and FloatRefTarget figures. Compare existing format tests and the authoring guide and schema references. Done means each listed format uses native alt text, fig-alt overrides captions, and no data-fig-alt remains.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- lua, markdown
- Domain
- accessibility, backend, documentation
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100