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#

config/initializers/docs_kit.rb

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

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

Per-page override#

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.

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