quarto-dev / quarto-dev/quarto-cli
a11y: margin layout breaks PDF structure tree for UA-2
Nobody has claimed this yet.
- Dominant language
- JavaScript
- Stars
- 6k
- Forks
- 458
- Avg merge
- 1d 9h
- Merged PRs (30d)
- 41
Description
With apologies, I do not have any LaTeX domain knowledge, therefore this issue will be a conversation between various instances of Claude.
TL;DR: there are paths forward, but the current recommendation is to use footnotes and not margin notes in order to produce accessible PDFs using LaTeX.
Errors:
StructTreeRoot shall not contain <P>/<Caption>/<Figure>/<Table>/<Div>/<Part>The structure tree root shall contain a single Document structure element<P> shall not contain <Aside>/<Part>/<P>
Cause: All these tests use margin layout (.column-margin or column: margin).
Quarto's filters generate:
\marginnote{\begin{footnotesize}...\end{footnotesize}}for text
(src/resources/filters/layout/latex.lua:215-238)\begin{marginfigure}...\end{marginfigure}for figures
(src/resources/filters/layout/latex.lua:554)\begin{margintable}...\end{margintable}for tables
(src/resources/filters/layout/latex.lua:643-663)
These come from the sidenotes and marginnote LaTeX packages (injected at
src/resources/filters/layout/meta.lua:106-116). These packages predate PDF
tagging and don't cooperate with tagpdf:
\marginnotecreates content in a separate output stream that escapes the
Document structure element entirely, placing children at StructTreeRoot.tagpdfassigns an<Aside>role to margin content but nests it inside an
active<P>context, which is invalid per PDF/UA-2.- The result is structure elements (
<P>,<Caption>,<Figure>, etc.) appearing
directly under StructTreeRoot instead of inside<Document>.
Files:
| File | Margin content |
|---|---|
2024/05/06/9582.qmd |
Multiple .column-margin divs with figures and text |
2024/06/24/10112.qmd |
R table with column: margin |
typst/margin-layout/margin-figure-crossref-interleaved.qmd |
Figures with .column-margin class |
article-layout/tables/compute-table-margin.qmd |
R table with column: margin |
2022/09/30/caption-footnotes/test.qmd |
Also affected (uses figure captions; see section 3) |
Problem in: LaTeX packages (sidenotes/marginnote). These packages are not
tag-aware. Fixing this requires either:
- Upstream patches to
sidenotes/marginnotefortagpdfcompatibility - A different LaTeX approach for margin content when tagging is enabled
- Skipping UA-2 validation for margin-layout tests until the ecosystem catches up
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 with the margin-layout fixtures listed in the issue and the filter paths in src/resources/filters/layout/latex.lua and meta.lua. Reproduce their UA-2 validation failures and inspect how sidenotes and marginnote interact with tagpdf. Done means the chosen supported approach no longer produces the reported structure-tree violations, or the affected tests are explicitly handled.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- latex, lua
- Domain
- accessibility, testing
- Issue type
- Bug
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100