Navigation

Navigation

Verto provides two complementary navigation systems for docs pages: a sidebar that organizes pages into collapsible groups, and an auto-generated table of contents that tracks your scroll position within a page.

The sidebar is configured through a single JSON file at content/navigation.json. It defines groups of pages, where each group becomes a collapsible section in the sidebar.

Structure

Each group has a group label and a flat list of items. Every item needs a title (displayed in the sidebar) and an href (the page's URL path):

{
  "docs": [
    {
      "group": "Getting Started",
      "items": [
        { "title": "Introduction", "href": "/docs/getting-started/introduction" },
        { "title": "Installation", "href": "/docs/getting-started/installation" }
      ]
    },
    {
      "group": "Core Concepts",
      "items": [
        { "title": "Inline Comments", "href": "/docs/core-concepts/inline-comments" }
      ]
    },
    {
      "group": "Features",
      "items": [
        { "title": "Dark Mode", "href": "/docs/features/dark-mode" },
        { "title": "Navigation", "href": "/docs/features/navigation" }
      ]
    }
  ]
}

Items within a group are flat. Each item maps directly to a single page.

Collapsible Groups

Each group header renders as a <details open> element with a chevron toggle. Groups start expanded by default, and readers can collapse sections they don't need. This keeps the sidebar scannable even as the number of pages grows.

Active Page Highlighting

The sidebar compares the current URL pathname against each item's href. When they match, the active page gets a blue accent bar on the left edge, bold text, and a subtle background highlight. You always know where you are.

Table of Contents

On the right side of every docs page, Verto displays a table of contents under an "On this page" header.

How It's Generated

The table of contents is extracted automatically from your MDX content. It picks up ## (H2) and ### (H3) headings only. H1 headings are excluded since they're reserved for the page title. The extraction is handled by lib/toc.ts, which parses heading nodes from the compiled MDX.

No configuration required. Write your headings, and they appear in the table of contents.

Scroll Tracking

As readers scroll through a page, the table of contents highlights the heading closest to the current viewport. This is powered by an IntersectionObserver that watches each heading element. The active heading updates in real time, giving readers a persistent sense of where they are in longer documents.

Responsive Behavior

The table of contents is visible on wider screens (above ~1280px) and hidden on smaller viewports. On narrower screens, the page content expands to fill the available width, and readers rely on the sidebar or scrolling for orientation.

Mobile Navigation

On screens below the lg breakpoint (~1024px), the sidebar is hidden entirely. In its place, a hamburger menu icon appears in the header.

Tapping the hamburger opens a full-screen drawer overlay with links to Docs and Blog sections. While the menu is open, body scrolling is locked so you won't accidentally scroll the page behind it. The menu dismisses when you press the Escape key or navigate to a page.

Adding Pages

To add a new page to the docs:

  1. Create your .mdx file in the appropriate directory under content/docs/
  2. Add frontmatter with title, description, and order fields
  3. Open content/navigation.json and add an entry to the relevant group's items array

The page will appear in the sidebar at the position you place it in the JSON array.