Implement toc-location option: left/right/body (bd-e2kpwy7n)

[cscheid]

Summary

Implements the toc-location option for HTML output (left, right, body), closing the gap tracked as bd-e2kpwy7n. This also un-inerts the banner toc-left header-class hook and the already-ported .page-columns.toc-left / .sidebar.toc-left SCSS.

Q1 implements this with a DOM postprocessor that moves nav#TOC into a template-emitted placeholder; q2 has no DOM-postprocessor stage, so placement is decided up front:

• New TocLocationTransform (Navigation phase, between TocRender and SidebarRender) normalizes the option, publishes rendered.navigation.toc-location + placement flags (toc-relocated / toc-left / toc-body / toc-in-sidebar), and produces quarto-template-params.banner-header-class: toc-left when a banner is active.
• Website regime (ProjectKind::Website, mirroring Q1's sidebar.ejs): SidebarRenderTransform appends the TOC block inside nav#quarto-sidebar after the nav items via a new sidebar_to_html_with_appended seam in quarto-navigation, or synthesizes a TOC-only floating sidebar (body classes nav-sidebar floating) when no sidebar is configured. sidebar: false still synthesizes, matching Q1's nav.sidebar || navbarTocLeft gate.
• Standalone regime (mirroring Q1's before-body-article.ejs): the template emits div#quarto-sidebar-toc-left.sidebar.toc-left and adds the toc-left grid class to #quarto-content.
• body: the TOC renders inside <main> between the title block and the body.
• A new toc-block template partial is shared by the three template-emitted placements (Rust twin toc_block_html for the sidebar merge).
• left-body / right-body warn (new Q-13-8 diagnostic + error docs page) and fall back to left / right (double-TOC clone tracked as bd-jclcm0in); unknown values warn and default to right.

Deliberate deviations from Q1 (design decisions recorded in claude-notes/plans/2026-08-14-toc-location.md):

• No empty #quarto-margin-sidebar shell when the TOC leaves the margin (Q1 keeps an empty zindex-bottom element).
• The body TOC keeps q2's decorated markup (nav-link, data-scroll-target) instead of Q1's plain list, anticipating scroll-spy support.

Docs: fills the guides/authoring/navigation.qmd stub with TOC + toc-location usage.

Follow-ups filed: bd-jclcm0in (*-body clones, carries the banner-gate constraint), bd-tqijrhsu (preview parity — q2 preview's TocSlot still renders the margin TOC), bd-eczdzfqo (pre-existing role=\"doc-toc\" on the sidebar nav now nests roles).

Test plan

• TDD: 11 new end-to-end integration tests (crates/quarto-core/tests/integration/toc_location.rs) written first and verified failing — both regimes of left, body, explicit-right-equals-default, banner composition, *-body/unknown fallback warnings.
• New template unit test pinning the margin-categories interaction (categories keep their margin shell when the TOC relocates).
• Zero snapshot changes — the right/default path is byte-stable.
• Full workspace suite green (12,111 tests); full cargo xtask verify passed including hub-client/WASM legs.
• Verified end-to-end through the real binary: the committed website repro renders nav#TOC inside nav#quarto-sidebar…sidebar-floating with body.floating and no margin sidebar; a standalone doc gets #quarto-content.toc-left + #quarto-sidebar-toc-left. Real-world validation against the Connect-docs api/index.html (201-entry TOC) planned for a follow-up session.

🤖 Generated with Claude Code

[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.