Add a tab

Minimum steps

Just drop a folder containing one or more .html pages (each with a <main class="doc-body"> block) under docs/pages/ — no index.html and no _tab.json required:

mkdir docs/pages/reference
# author one or more pages, e.g. docs/pages/reference/overview.html

With ./run_dev.sh running, a Reference tab appears automatically (the dev server bakes the chrome for you). If the server isn't running, bake once with python3 docs/_lib/_wrap_handwritten.py. The tab opens to its first page; any subfolders become collapsible sidebar dividers, recursively (see Conventions §1). A tab with no serveable .html at all is silently skipped.

Everything below is optional — add a _tab.json only when you want to override the auto behaviour.

Controlling tab order

Tabs sort by order_priority (smaller is further left), then by directory name. Set it in the new tab's _tab.json:

{
  "label": "Reference",
  "order_priority": 30
}

Giving the tab a non-slug label

The directory name determines the URL (/pages/reference/...). The label shown in the header defaults to the title-cased directory name; override it with label:

{
  "label": "API Reference",
  "order_priority": 30
}

Result: the URL stays at pages/reference/..., the tab reads "API Reference".

Picking an accent color

The key field selects a CSS accent class from docs/assets/style.css (e.g. guide, designdoc, capability, research, architecture). Pick one, or add your own accent variables to the stylesheet:

{
  "label": "API Reference",
  "key": "architecture",
  "order_priority": 30
}

A tab only renders sidebar entries for pages inside its sections. For a flat tab (files directly in the tab dir), add one section pointing at the tab root with "dir": "":

{
  "label": "API Reference",
  "order_priority": 30,
  "sections": [
    {"label": "Reference", "dir": "", "key": "architecture"}
  ]
}

For a tab organized into subdirectories, either list a section per subdir or omit sections to auto-discover them. See Sidebar sections & sub-sections.

Removing a tab

Delete the directory and re-run the wrap script. Any links that pointed into it will now 404 — grep for the old path to find them: grep -rn 'pages/reference/' docs/.