TOC: list a heading wrapped in a div that carries an id

[gordonwoodhull]

Put an id on a fenced div and the heading inside it vanished from the page's table of contents:

::: {#download-hero}
### Recommended for you
:::

The heading rendered, its <section> was anchorable, and a reader could scroll to it — but there was no way to navigate to it. No warning, exit 0. Quarto 1 lists it.

The id is what triggers this. A div with no attributes, or with only a class, is fine, because sectionization folds that wrapper into the <section> it holds and the heading ends up an ordinary top-level section. A wrapper carrying an id can't be folded — its id would collide with the section's own — so the section stays nested one level down, and the TOC walk stopped at the first non-section div it met without looking inside.

The walk now sees through a wrapper whose sole content is another div, which is pandoc's rule (toTOCTree, jgm/pandoc#8402). It recurses rather than unwrapping a single level, so a section buried under several wrappers is reached too — Quarto 1 lists those as well.

What still ends the walk is a wrapper holding anything besides a lone div, which is where filter-built chrome stops — though not always at its outermost div, and the distinction is worth stating because it is thinner than it looks. A titled callout and a resolved tabset each put two blocks side by side (header beside body, nav list beside pane container), so the walk stops at the outer div. An untitled callout does not: it emits a lone .callout-body.d-flex, so the walk descends one level and stops there instead, on the icon container beside the body container. Pandoc descends that same level, so Quarto 1 stops in the same place. Both stops rest on a sibling block that another transform is free to move, so each now has a test, and panel_tabset_resolve.rs records that its nav Plain is load-bearing for the TOC walk rather than just for markup.

Headings inside a tab pane, a callout, or a blockquote therefore stay out of the table of contents, as does a heading with prose or a sibling section beside it inside the same wrapper — all matching both pandoc and Quarto 1.

Tests

The new tests in crates/pampa/tests/integration/test_toc_wrapper_divs.rs drive markdown through the real pair, readers::qmd::read → sectionize_blocks → generate_toc. That matters here: the bug was an interaction between the absorb rule and the walk, and toc.rs's unit tests hand-build the sectionized AST on both sides of it, so either half could change without the other's tests noticing. They pin the eight wrapper shapes, stacked wrappers, and the two ways a wrapper can hold more than one block. All three positive tests fail without the new match arm; the negative controls are invariant, as they should be.

test_non_section_div_terminates_the_walk pinned the old behaviour using a tabset shape PanelTabsetResolveTransform does not emit — that transform's own unit test asserts the outer div holds two blocks. It is now test_resolved_tabset_pane_is_not_reached and uses the real shape, so it guards what the transform actually produces. test_untitled_callout_body_is_not_reached is new and pins the other stop.

Verification

Checked against a fixture covering eight wrapper shapes: q2 now agrees with Quarto 1 on every one, positive and negative. Callout, tabset and single-tab-tabset shapes rendered through the binary produce tables of contents identical to Quarto 1's. On the Positron website's download page, which wraps its hero section in ::: {#download-hero .download-hero}, the "Recommended for you" entry is back and the page's table of contents matches Quarto 1's entry for entry.

One known consequence

DocumentProfile::extract_outline shares generate_toc but runs pre-transform, before callouts and tabsets are resolved into chrome. A single-child id-bearing callout or tabset therefore now reaches profile.outline although the rendered TOC still excludes it. That is the existing bd-ca17fck0 divergence — profile outline computed pre-transform disagreeing with the post-transform TOC — extended from anonymous wrappers to id-bearing ones. Nothing outside tests consumes profile.outline today; noted on that strand rather than fixed here.

Fixes bd-toc-skips-headings-in-id-div-1jorg679.

[posit-snyk-bot]

✅ Snyk checks have passed. No issues have been found so far.

Status	Scan Engine	Critical	High	Medium	Low	Total (0)
✅	Open Source Security	0	0	0	0	0 issues
✅	Licenses	0	0	0	0	0 issues

💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse.

[cscheid]

I think the omission is now intentional, though we can talk about it!