# Navigation

> How ShellDocs builds the sidebar. meta.json, order, dividers, subsections, hidden pages.

Source: https://shelldocs.shellui.dev/docs/authoring/navigation

The sidebar, breadcrumb, and prev/next chrome all derive from a **navigation graph** built at startup by walking `content/docs/**`. You control ordering with `meta.json`; presence is automatic.

## The core rule

**Files decide presence, `meta.json` decides order.**

Drop a `.md` into a folder, it shows up. `meta.json` lists the slugs you want to control ordering for; anything not listed appears alphabetically after your explicit list.

## Basic `meta.json`

Each folder can carry a `meta.json`:

```json
{
  "title": "Getting Started",
  "pages": ["installation", "quick-start", "project-structure", "configuration"]
}
```

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `title` | `string?` |  | Folder display name shown in the sidebar section header. Falls back to a title-cased folder name (getting-started → Getting Started). |
| `pages` | `array` |  | Ordered list of slug entries. Each entry is a slug, three dashes for a divider, or a subsection object. |
| `hidden` | `string[]?` |  | Slugs of pages / subfolders that should route (URLs resolve) but not appear in the sidebar. |

## Slug entries

A slug is a file basename without `.md`, or a subfolder name : both resolve the same way.

```json
{ "pages": ["introduction", "getting-started", "components"] }
```

- `"introduction"` → `content/docs/introduction.md`
- `"getting-started"` → `content/docs/getting-started/` (subfolder becomes a section)
Don't give a page and a folder the same name in one directory. For a landing page at a folder's URL, put an `index.md` inside the folder.

## Dividers

The literal string `"---"` becomes a section divider in the sidebar : a thin rule with no click affordance.

```json
{
  "pages": [
    "introduction",
    "---",
    "getting-started",
    "---",
    "components",
    "cli"
  ]
}
```

Use dividers to group related pages without wrapping them in a nested section.

## Subsections

An object entry with `title` and `pages` renders a nested labeled group without needing a real subfolder. Handy when the content lives under a flat structure but you want visual grouping.

```json
{
  "pages": [
    "introduction",
    {
      "title": "Guides",
      "pages": ["installation", "quick-start"]
    },
    {
      "title": "Reference",
      "pages": ["components", "cli", "tokens"]
    }
  ]
}
```

Subsection pages still resolve at their normal URLs : the subsection is a sidebar-only construct.

## Auto-append

Files or folders not listed in a `meta.json` are **appended alphabetically after your explicit list**. So dropping a new `.md` into `content/docs/components/` shows it in the sidebar without editing `meta.json`.

> **Ordering that scales**
>
> For the top of the sidebar, hand-order the important pages via `pages`; let everything else auto-append. You get intentional lead-in ordering + zero-effort discovery for new content.

## Auto-append order

Within the auto-appended group:

1. **Subfolders first**, alphabetically by folder name.
2. **Pages after**, ordered by frontmatter `order` (ascending), then alphabetically by title as a tie-breaker.

Set `order: N` in a page's frontmatter to control its position within the auto-appended group.

## No `meta.json`

If a folder has no `meta.json`, everything auto-orders:

1. Subfolders first, alphabetically.
2. Pages after, `order` then alphabetical.

## Hidden pages

`hidden` lists slugs (page or folder) that should **route** but not appear in the sidebar. Their URLs still resolve, and their content is still indexed by search : they just don't show up in navigation.

```json
{
  "pages": ["introduction", "getting-started"],
  "hidden": ["landing", "archived"]
}
```

Use cases:

- Landing pages reached only through the package selector
- Private drafts in-flight
- Archived content kept for URL stability

Hidden folder children are still indexed : the framework walks the tree and stores every URL, so deep links work.

## URLs

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `content/docs/introduction.md` | `→` |  | /docs/introduction |
| `content/docs/getting-started/installation.md` | `→` |  | /docs/getting-started/installation |
| `content/docs/guides/index.md` | `→` |  | /docs/guides (index.md gets the folder URL) |

## Index pages

An `index.md` in a folder is that folder's landing page. In the sidebar the section label links to it and is highlighted when it is the current page; the page is not listed a second time underneath. In a collapsible section the chevron is a separate button, so the label can be a link.

List it first in the folder's `meta.json`, or leave it out and let it sort by `order`:

```json
{ "title": "Authoring", "pages": ["index", "frontmatter", "fenced-code"] }
```

## Folder URLs redirect

A folder with no `index.md` has no page of its own. Visiting its URL redirects to the first page inside it, so `/docs/components` goes to `/docs/components/callout` and `/docs` goes to the first page of the docs. Details and custom rules are in [Redirects](https://shelldocs.shellui.dev/docs/guides/redirects.md).

## `title` on a subfolder

Set `title` in the folder's `meta.json` to control the sidebar section header. It falls back to a title-cased folder name, which is wrong for acronyms: a `cli` folder becomes "Cli". Set `"title": "CLI"` for those.

## Versions

When docs versions are configured, the sidebar shows only the current version's pages, and prev/next and search stay inside it. See [Versioning](https://shelldocs.shellui.dev/docs/guides/versioning.md).

## See also

- [Frontmatter](https://shelldocs.shellui.dev/docs/authoring/frontmatter.md): Per-page title, description, order.
- [Redirects](https://shelldocs.shellui.dev/docs/guides/redirects.md): Folder URLs, version roots and moved pages.
- [Versioning](https://shelldocs.shellui.dev/docs/guides/versioning.md): One docs tree per released version.
- [ShellDocs.Core](https://shelldocs.shellui.dev/docs/packages/core.md): NavigationGraph API : programmatic traversal.