feat: floating Table of Contents

[mschmidtkorth]

Hello, this PR replaces the static ToC widget at the top of a page with a floating, persistent navigation panel that follows users as they scroll through documents. I did touch the original ToC code so please have a good look :)

Note Let me know if this is better suited as a plugin… putting it as draft as I noticed some weird behavior with widgets being killed 'randomly' jumping to different AST sections.

Rationale: You can quickly jump through the document without having to scroll back to the top.

Implementation

• Replaces widgets.toc() with widgets.floatingToc()
• Uses HTML instead of Markdown for better styling control (via web/styles/main.scss classes)
• Is responsive incl. mobile
• Hides border frame and refresh button of the original implementation (class="sb-lua-top-widget") via .toc-hidden-container class, which might not be the best solution
• Can still be disabled via disableTOC frontmatter as built on top of existing implementation, but it is now a string property. I've kept the property name for legacy purposes, but would have preferred displayTOC = true|false|always
• Keyboard navigation (not yet committed)
• Search (not yet committed)

---
  pageDecoration:
    disableTOC: true   # Default - shows TOC (opacity 0.1, hover to 1.0)
    disableTOC: false  # Disable TOC completely
    disableTOC: never  # Always visible TOC (opacity 1.0); example use case: index pages like https://silverbullet.md
---

Possible enhancements

• Indicate current heading (would require more extensive JS)
• Keyboard shortcuts to navigate to next/previous heading (again JS)

Before

After
(peeking but not hovered; deliberately barely visible; disableTOC: false|never)

(hovered)

(mobile)