Skip to content

Title every appendix section, localized, and drop the footnotes rule (bd-v9zs83zj) - #520

Merged
cscheid merged 3 commits into
mainfrom
feature/bd-v9zs83zj-footnotes-appendix-heading
Aug 13, 2026
Merged

Title every appendix section, localized, and drop the footnotes rule (bd-v9zs83zj)#520
cscheid merged 3 commits into
mainfrom
feature/bd-v9zs83zj-footnotes-appendix-heading

Conversation

@cscheid

@cscheid cscheid commented Aug 13, 2026

Copy link
Copy Markdown
Member

Closes bd-v9zs83zj.

q2's footnotes appendix had no visible heading. appendix.rs pushed the extracted
footnotes Div verbatim, where the branch directly above it calls
wrap_bibliography. That asymmetry is the bug in one sentence; this adds the missing
wrap_footnotes.

Two things widened the fix beyond the strand's title, both agreed before implementation.

1. The <hr> goes too — the strand's premise was wrong here

The strand states the <hr /> is correct and only the heading is missing. It isn't.
Quarto 1's prependHeading (format-html-shared.ts:405-409) inserts the heading and
removes the rule
— the heading takes over as the section separator. Shipping the
heading alone would leave q2 emitting both, and the Connect-docs diff this strand exists
to close would not have closed.

The strip lives in the appendix transform, not in create_footnotes_section, so the
rule survives when appendix processing is off (appendix-style: none, book: true).
That matches Q1, which only titles footnotes from inside processDocumentAppendix.

2. All five headings, not one

References / Reuse / Copyright / Citation were hardcoded English despite
section-title-* keys existing in _language.yml and being fully translated across
every _language-*.yml. They now route through the same localized lookup, following
toc_generate.rs's precedence (localized term > English literal — the literal covering
stage-less unit tests, where LanguageTerms::from_meta returns None).

Heading shape

class="anchored quarto-appendix-heading", no id — matching Q1 exactly.

  • quarto-appendix-heading activates SCSS q2 already shipped but never matched
    (_bootstrap-rules.scss). This is a real visual change.
  • anchored is inert in q2: in Q1 it is an AnchorJS selector hook, and q2 ships
    neither the runtime nor any rule for it. Emitted so the appendix is already correct
    when heading anchors land — follow-up bd-5kf2dnw4, which must skip headings that
    already carry the class, since Vec<String> push is not idempotent the way
    classList.add is.

Titles split into canonical Str/Space inlines rather than one Str with embedded
spaces. Never observable in English (every title is one word); required once localized
(Derechos de autor).

Review notes

The two must-not-change cases — appendix-style: none and book: true — passed
before and after the change. They are the guard on the conditional <hr> strip.

appendix_title filters an empty resolved term before falling back: a language term set
to null round-trips as Some(""), which would emit a heading with no text.

Not using pampa's split_string_to_inlines — it is Lua-module-scoped and hardcodes
By::unknown() provenance; the local helper carries By::appendix().

Testing

7 new unit tests in appendix.rs + 3 smoke-all fixtures, all confirmed failing
first
(6 unit failures, 7 regex mismatches).

Snapshots: zero changed. Verified this is real coverage rather than a blind spot —
no .snap in the tree contains appendix HTML at all (quarto-appendix /
doc-endnotes / quarto-bibliography all return nothing). The appendix is covered by
smoke-all and unit tests instead.

Full cargo xtask verify (not --skip-hub-build): 14/14 steps, 11801 passed, 197
skipped
.

End-to-end, three ways:

  1. cargo run --bin q2 -- render<h2 class="anchored quarto-appendix-heading">Footnotes</h2>,
    no <hr>. Byte-identical to Q1.
  2. Computed styles read back from a real browser page: font-weight 600,
    font-size 17px (= 1em), margins 0, border-bottom none, opacity .9 — every
    rule in the previously-dead block now applies. #footnotes hr → 0.
  3. The user/manifest Connect-docs page re-rendered and compared against the Q1
    reference site: previously 0 occurrences of quarto-appendix-heading, now matching
    exactly.

Design rationale and the full investigation are in
claude-notes/plans/2026-08-12-footnotes-appendix-heading.md.

Unrelated, filed separately

The first full verify failed at step 4 on a tree-sitter corpus case this change never
touches. Chased down: it reproduces on pristine main with the tree stashed,
tree-sitter generate yields no diff (so parser.c is in sync with grammar.js), and
it passes 3/3 after a forced rebuild. The culprit is the stale gitignored
markdown.dylib build cache. Filed as bd-7ilvb5r2; not a grammar bug and not this
change.

🤖 Generated with Claude Code

Plan skeleton + repro. Verdict: ready to design, pending 4 questions.

Fix site is one line: appendix.rs:156 pushes the footnotes Div verbatim
where the branch above it calls wrap_bibliography. Two corrections to the
strand's premise: (1) Q1 deletes the <hr> when it inserts the heading, so
heading-only would not close the Connect-docs diff; (2) the four existing
appendix headings are all hardcoded English despite their section-title-*
language keys existing and being fully translated.
All four questions answered. Scope: all five appendix headings localized
via section-title-*, footnotes gains a heading and loses its <hr>, both
Q1 classes emitted, no heading id.

Q3 research (Finding 5): .anchored is a pure AnchorJS selector hook with
no styling of its own, so emitting it in q2 is inert today and carries no
visual risk -- the inverse of quarto-appendix-heading, which activates
substantive dead CSS. Follow-up bd-5kf2dnw4 filed to make it live; its
non-obvious constraint is that class-push is not idempotent, unlike Q1's
classList.add, so the future document-wide pass must skip headings that
already carry the class.
…(bd-v9zs83zj)

q2's footnotes appendix had no visible heading: appendix.rs pushed the
extracted footnotes Div verbatim where the branch directly above it calls
wrap_bibliography. Add the missing wrap_footnotes.

Two things widened the fix beyond the strand's title, both approved:

1. The <hr> goes too. Quarto 1's prependHeading inserts the heading AND
   removes the rule (format-html-shared.ts:405-409) -- the heading takes
   over as the separator. Adding the heading alone would have left q2
   emitting both and would NOT have closed the Connect-docs diff the
   strand exists to close. The strip lives in the appendix transform, not
   in create_footnotes_section, so the rule survives when appendix
   processing is off (appendix-style: none, book: true) -- which is also
   what Q1 does, since it only titles footnotes from inside
   processDocumentAppendix.

2. All five headings, not one. References/Reuse/Copyright/Citation were
   hardcoded English despite section-title-* keys existing in
   _language.yml and being fully translated. They now route through the
   same localized lookup, following toc_generate.rs's precedence
   (localized term > English literal, the literal covering stage-less
   unit tests where LanguageTerms::from_meta returns None).

Headings carry Q1's classes 'anchored quarto-appendix-heading' and no id.
quarto-appendix-heading activates SCSS q2 already shipped but never
matched; 'anchored' is inert here -- in Q1 it is an AnchorJS selector
hook, and q2 ships neither the runtime nor any rule for it. Emitted so
the appendix is already correct when heading anchors land (bd-5kf2dnw4,
which must skip headings that already carry it -- Vec<String> push is not
idempotent the way classList.add is).

Titles split into canonical Str/Space inlines rather than one Str with
embedded spaces. Never observable in English (every title is one word);
required once localized ('Derechos de autor').

Tests: 7 new unit tests in appendix.rs + 3 smoke-all fixtures, all
confirmed failing first. The two must-not-change cases (appendix-style:
none, book: true) passed before and after.

SNAPSHOTS: zero changed. Verified this is real coverage, not a blind
spot -- no .snap in the tree contains appendix HTML at all (grep for
quarto-appendix/doc-endnotes/quarto-bibliography returns nothing). The
plan had predicted churn; the prediction was wrong.

Full cargo xtask verify green: 14/14 steps, 11801 passed, 197 skipped.
End-to-end render inspected, computed styles read back from a browser,
and the user/manifest Connect-docs page now matches the Q1 reference
byte-for-byte. Details in
claude-notes/plans/2026-08-12-footnotes-appendix-heading.md.
@posit-snyk-bot

posit-snyk-bot commented Aug 13, 2026

Copy link
Copy Markdown

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
cscheid merged commit 0dcd7e8 into main Aug 13, 2026
8 checks passed
@cscheid
cscheid deleted the feature/bd-v9zs83zj-footnotes-appendix-heading branch August 13, 2026 13:52
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants