feat(wiki): enhanced table of contents — collapsible, numbered, floating #673

New Issue

2026-06-21T13:40:45Z

jmiller commented

2026-06-21 13:40:45 +00:00

Summary

Enhance the existing wiki table of contents with collapsible sections, optional numbering, scroll-tracking, and per-page control via frontmatter.

Current State

WikiSidebarTocHTML is generated from rctx.TocHeadingItems in renderViewPage() and rendered in the sidebar
The ToC is static — no collapsing, no numbering, no scroll tracking
Cannot be disabled or repositioned per page

Proposed Enhancements

1. Collapsible Sections

Each ToC heading with sub-headings gets a collapse/expand toggle
Default: H2 sections expanded, H3+ collapsed
State persisted in localStorage per page

2. Section Numbering

Optional numbered sections like Wikipedia: 1, 1.1, 1.2.1
Controlled via frontmatter: toc_numbered: true
Numbers appear in both the ToC and optionally in the content headings

3. Floating/Sticky ToC

On long pages, the ToC sidebar becomes sticky as the user scrolls
Active section highlighted in the ToC based on scroll position (scroll-spy)
CSS position: sticky with IntersectionObserver for heading tracking

4. Per-Page Control via Frontmatter

---
toc: false          # disable ToC entirely
toc: inline         # render ToC inline at top of content instead of sidebar
toc_numbered: true  # enable section numbering
toc_depth: 3        # only show H1-H3 in ToC
---

Files to Modify

File	Change
`routers/web/repo/wiki.go`	Parse ToC frontmatter options, pass to template
`templates/repo/wiki/view.tmpl`	Conditional ToC placement (sidebar vs inline)
`web_src/js/features/repo-wiki.ts`	Scroll-spy, collapsible ToC logic
`web_src/css/`	Sticky ToC, active section highlighting

Wikipedia Parity

Wikipedia's ToC is auto-generated, numbered, and collapsible — a key navigation aid on long articles.

## Summary Enhance the existing wiki table of contents with collapsible sections, optional numbering, scroll-tracking, and per-page control via frontmatter. ## Current State - `WikiSidebarTocHTML` is generated from `rctx.TocHeadingItems` in `renderViewPage()` and rendered in the sidebar - The ToC is static — no collapsing, no numbering, no scroll tracking - Cannot be disabled or repositioned per page ## Proposed Enhancements ### 1. Collapsible Sections - Each ToC heading with sub-headings gets a collapse/expand toggle - Default: H2 sections expanded, H3+ collapsed - State persisted in `localStorage` per page ### 2. Section Numbering - Optional numbered sections like Wikipedia: `1`, `1.1`, `1.2.1` - Controlled via frontmatter: `toc_numbered: true` - Numbers appear in both the ToC and optionally in the content headings ### 3. Floating/Sticky ToC - On long pages, the ToC sidebar becomes sticky as the user scrolls - Active section highlighted in the ToC based on scroll position (scroll-spy) - CSS `position: sticky` with `IntersectionObserver` for heading tracking ### 4. Per-Page Control via Frontmatter ```markdown --- toc: false # disable ToC entirely toc: inline # render ToC inline at top of content instead of sidebar toc_numbered: true # enable section numbering toc_depth: 3 # only show H1-H3 in ToC --- ``` ### Files to Modify | File | Change | |------|--------| | `routers/web/repo/wiki.go` | Parse ToC frontmatter options, pass to template | | `templates/repo/wiki/view.tmpl` | Conditional ToC placement (sidebar vs inline) | | `web_src/js/features/repo-wiki.ts` | Scroll-spy, collapsible ToC logic | | `web_src/css/` | Sticky ToC, active section highlighting | ## Wikipedia Parity Wikipedia's ToC is auto-generated, numbered, and collapsible — a key navigation aid on long articles.

jmiller added the feature: wiki label 2026-06-21 13:40:45 +00:00

jmiller referenced this issue from a commit

2026-06-22 00:34:02 +00:00

feat(wiki): enhanced ToC — collapsible, inline, sticky, frontmatter control (#673)

jmiller closed this issue

2026-06-22 00:34:34 +00:00

jmiller referenced this issue from a commit

2026-06-23 14:09:50 +00:00

docs: update README and changelog with wiki features documentation

Sign in to join this conversation.