Sidebar sections & sub-sections

The left sidebar of a tab is built from its sections (declared in _tab.json) plus the actual subdirectory tree on disk. This recipe shows the three shapes you'll reach for.

Flat tab, one section

Files live directly in the tab directory, no subfolders. Point one section at the tab root with "dir": "" and pin the order. Both tabs in this site use this shape:

{
  "label": "Guide",
  "sections": [
    {"label": "Guide", "dir": "", "key": "guide",
     "order": ["index", "installation", "quick-start", "why", "conventions"]}
  ]
}

Grouped by subdirectory

Organize files into subfolders and give each one a section. The section's dir is relative to the tab:

docs/pages/knowledge-base/
├── getting-started/   index.html, setup.html
├── benchmarks/        vln.html, eqa.html, vla.html
└── methods/           navgpt.html, mapgpt.html

{
  "label": "Knowledge Base",
  "sections": [
    {"label": "Getting Started", "dir": "getting-started", "key": "guide"},
    {"label": "Benchmarks", "dir": "benchmarks", "key": "guide"},
    {"label": "Methods", "dir": "methods", "key": "guide",
     "order": ["navgpt", "mapgpt"]}
  ]
}

Nested subdirectories are discovered recursively: a subfolder with its own index.html becomes a collapsible group whose label is that page's title; without an index.html it becomes a non-clickable group label. The group auto-expands when it contains the active page.

Auto-discovery (no sections at all)

Omit sections from _tab.json (or skip the file entirely) and the scanner creates one section per immediate subdirectory, alphabetically, each labelled from the title-cased folder name. Good for "just works" tabs where you don't care about ordering or custom labels.

Pinning order without sections: `_order.json`

To fix the order inside a folder without declaring sections, drop an _order.json in it: a JSON list of names, where a name is a subfolder or a page stem. Listed entries come first in that order; the rest follow alphabetically.

["getting-started", "concepts", "faq"]

Advanced section fields

Field	Effect
`only_listed`	`true` = the section shows only the stems named in its `order` (plus the dir's `index.html`). Lets several sections split one directory between them.
`no_auto_index`	With `only_listed`: do not add the dir's `index.html` automatically (when another section already shows it).
`nav_key`	Override the key that remembers the section's open/closed state. Required when two sections share a `dir`, or they open and close together.
`groups`	A list of virtual collapsible sub-groups appended after the section's own pages. Each entry takes `label` / `dir` / `order` / `only_listed` / `nav_key`, like a section. Pages from another directory nest under this section without moving files.

Sections vs. subfolders — which to use

One flat section when the tab has a handful of peer pages.
Subfolders + curated sections when you want named groups, control over order, and short, stable per-group URLs.
Auto-discovery when the structure is still in flux and you don't want to maintain a config.

Because grouping is expressed in _tab.json and on the filesystem — not in the page content — you can regroup the sidebar by editing one file and re-running the wrap script, without touching any page.