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-alt should override caption-derived alt text when both are present
fig-alt should not appear as data-fig-alt or 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.lua Image handler
- LaTeX Figure nodes:
layout/pandoc3_figure.lua
- Typst:
quarto-post/typst.lua Image handler
- FloatRefTarget (all non-HTML):
quarto-pre/figures.lua sets image.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
fig-altis Quarto's attribute for providing alternative text on images, distinct fromthe 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-alteither becomes a non-functionaldata-fig-altHTML attributein markdown output, or is silently dropped in docx.
How it should work
When
fig-altis set on an image:fig-alt, using the format's native mechanismfig-altshould override caption-derived alt text when both are presentfig-altshould not appear asdata-fig-altor any other non-functional attributeCurrent state by format
Two code paths matter: simple images (no cross-ref, no
#fig-id) and cross-referencedfigures (FloatRefTarget).
fig-align+ no captiondata-fig-altaltdiscarded by rendererdata-fig-altRoot cause
fig-altconversion is implemented per-format in scattered locations:quarto-post/html.luaImage handlerlayout/pandoc3_figure.luaquarto-post/typst.luaImage handlerquarto-pre/figures.luasetsimage.attributes["alt"]Markdown formats have no conversion at all. For markdown output with
raw_htmlenabled(hugo-md, gfm, md), Pandoc falls back to
<img>HTML for images with custom attributes.Since
fig-altis not a standard HTML attribute, Pandoc prefixes it withdata-→data-fig-alt.Documentation gap
The authoring guide presents
fig-altwithout format caveats but only shows HTML output examples. The YAML cellreference schema (
formatsfield forfig-alt) explicitly lists only HTML-familyformats. The 1.9 PDF/Typst accessibility support is not yet reflected in the schema.
No documentation warns that
fig-altis silently dropped in gfm, hugo-md, docx, orother markdown formats.
Additional related issues
fig-capbecomes alt text instead of figcaption in hugo-mdfig-altnot supported for mermaid/diagrams