Skip to content

Epic: fig-alt not propagated to output across multiple formats #14348

@cderv

Description

@cderv

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:

  1. The output should contain alt text derived from fig-alt, using the format's native mechanism
  2. fig-alt should override caption-derived alt text when both are present
  3. 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

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions