quarto-dev / quarto-dev/quarto-cli

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

Open
#14,348 0 comments 2 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

accessibility epic figures
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:

  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

  • #11478 — fig-cap becomes alt text instead of figcaption in hugo-md
  • #3873, #9003 — fig-alt not supported for mermaid/diagrams
  • #14338 — PDF validation should fail with no alt text

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.