Reference

# On this page

docs-kit builds a scroll-spy table of contents from your Section headings — no config required.

## Automatic TOC

docs-kit builds an **On this page** table of contents from your page's `DocsUI::Section` headings automatically — no config needed. As you scroll, scroll-spy highlights the section you're currently reading.

This very page has one — look to the right.

## Three placements

The TOC renders in one of three spots, or not at all.

| Mode | Placement |
| --- | --- |
| `:panel` | A sticky card top-right of the content column (default). |
| `:toggle` | A floating button top-right that opens a dropdown. |
| `:sidebar` | Nested under the active nav item in the left sidebar. |
| `false` | No auto-TOC. |

## Setting the default

```ruby
DocsKit.configure do |c|
  c.on_page_default = :panel
end
```

Sets the placement for **every** page unless a page overrides it.

## Per-page override

```ruby
class Views::Docs::Pages::Deploy < DocsUI::Page
  title "Deploy"
  on_page :toggle   # :panel | :sidebar | :toggle | false

  def content
    # ...
  end
end
```

Declare `on_page` in a `DocsUI::Page` subclass to override the default for that page only. Accepts `:panel`, `:toggle`, `:sidebar`, or `false`.

## How it works

The TOC is pure client-side. The docs-nav Stimulus controller reads `section[id]`, `h2[id]`, and `h3[id]` from the DOM, then an `IntersectionObserver` drives the scroll-spy highlight as sections enter the viewport.

Short pages — fewer than the minimum headings — hide the TOC automatically.

> **Tip:** Headings come from `DocsUI::Section` ids, so structure your page with Sections to get a good TOC.