---
name: pagesmith-docs-configure-nav
description: Configure sidebar, top-nav, and section ordering in a @pagesmith/docs site using meta.json5 files and page frontmatter. Use when the user wants to reorder, hide, rename, group, pin, or add external links to docs navigation, or when a page is missing from the sidebar.
allowed-tools: Bash(npx pagesmith-docs *)
---

# Configure Pagesmith Docs Navigation

Pagesmith generates the whole nav tree from the filesystem plus two sources of declarative config:

- `meta.json5` files (one per section and one at the root).
- `title`, `order`, and `draft` in page frontmatter.

There is no central `navigation.json`. Edit the nearest `meta.json5` or the page itself.

## Read the locally installed reference first

Before editing meta files or running CLI commands, open `node_modules/@pagesmith/docs/REFERENCE.md`, `node_modules/@pagesmith/docs/schemas/docs-root-meta.schema.json`, and `node_modules/@pagesmith/docs/schemas/docs-section-meta.schema.json` in the consumer's project. They are version-matched to the installed package and authoritative for navigation fields and CLI flags. If they disagree with this skill or general training data, follow the local files.

Always invoke the CLI through `npx pagesmith-docs <command>` (or via `package.json` scripts) so it resolves to the project's `node_modules/.bin` rather than a globally installed binary that may be a different version.

## How Pagesmith resolves navigation

For each folder under `contentDir`:

1. Read `meta.json5` (if present): `title`, `order`, `collapsed`, `pages`, `header`, `sections`.
2. For each page file, read `title`, `description`, `order`, `draft` from frontmatter.
3. Folders without `meta.json5` fall back to:
   - Title derived from the folder name (`getting-started` → "Getting Started").
   - Order = alphabetical.
   - Pages = all markdown files in the folder (sorted by `order` then title).

## Root `meta.json5`

Lives at `<contentDir>/meta.json5`. Controls top-level nav:

```json5
{
  $schema: "./node_modules/@pagesmith/docs/schemas/docs-root-meta.schema.json",
  sections: ["guide", "reference"],
  header: [
    { label: "Guide", path: "/guide" },
    { label: "Reference", path: "/reference" },
    { label: "GitHub", href: "https://github.com/<owner>/<repo>" },
  ],
}
```

- `sections` — ordered list of folder slugs that appear in the sidebar. Omit a section here to hide it from the generated nav.
- `header` — items in the top navigation bar. Use `path` for internal routes (honors `basePath`) and `href` for absolute URLs.

## Section `meta.json5`

Lives at `<contentDir>/<section>/meta.json5`. Controls the section's sidebar group:

```json5
{
  $schema: "../../node_modules/@pagesmith/docs/schemas/docs-section-meta.schema.json",
  title: "Getting Started",
  order: 1,
  collapsed: false,
  pages: [
    "install",
    "quickstart",
    { path: "first-page", title: "Your First Page" },
    { label: "Changelog", href: "https://github.com/.../releases" },
  ],
}
```

### `pages` entry shapes

| Shape                                        | Meaning                                            |
| -------------------------------------------- | -------------------------------------------------- |
| `'install'`                                  | Render `<section>/install.md` using its own title. |
| `{ path: 'install' }`                        | Same as above; explicit form.                      |
| `{ path: 'install', title: 'Installation' }` | Override the sidebar label only.                   |
| `{ label: 'X', href: 'https://…' }`          | External link in the sidebar.                      |

### Controlling behavior

- Omit `pages` entirely to include every file in the folder, ordered by frontmatter `order` then title.
- Include a `pages` array to make order authoritative — files not listed are still served by URL but hidden in the sidebar.
- `order` at the section level determines sidebar group order across the sibling sections under the parent.
- `collapsed: true` starts the group collapsed in the sidebar.

## Page-level knobs (frontmatter)

```md
---
title: Your First Page
description: ...
order: 2
draft: true
---
```

- `order` — lower values come first inside the parent section.
- `draft: true` — visible in `dev`, excluded from `build`. Don't link to drafts from non-drafts.

## Listing pages

A section without an explicit `index.md` or `README.md` auto-generates a listing page at `/section/` that enumerates the section's children. If you want a tailored landing, add a `README.md` with its own frontmatter; Pagesmith stops generating the listing automatically.

## Common tasks

### Pin a page to the top of its section

```md
---
title: Overview
order: 0
---
```

### Hide a page from the sidebar but keep it reachable

Either:

- Remove it from the section's `pages` array (when `pages` is used), or
- Set `draft: true` (also hides it from the production build).

Pagesmith has no "unlisted" flag; pick one of the above.

### Add an external link to the sidebar

Inside the section's `meta.json5`:

```json5
pages: [
  'install',
  'quickstart',
  { label: 'API docs (external)', href: 'https://api.example.com' },
],
```

### Rename a page without moving the file

Set `title` in the section's `meta.json5` entry. Do not rename the file — URLs would break.

### Reorganize sections entirely

1. Create the new folder under `contentDir`.
2. Move the markdown files.
3. Update each section's `meta.json5` (`title`, `order`, `pages`).
4. Update the root `meta.json5` `sections` to control top-level order.
5. Run `npx pagesmith-docs build` to catch dangling links.

## Verify

```bash
npx pagesmith-docs dev
```

`meta.json5` edits reload live — no restart needed. Always follow up with:

```bash
npx pagesmith-docs build
```

so the build surfaces missing slugs, invalid `pages` entries, or schema errors before deploy.

## Gotchas

- `pages` entries must match file names without extension. `install.md` maps to `'install'`. Mismatches silently drop the entry from the sidebar.
- Nested folder slugs need a path segment: `pages: ['advanced/caching']`, not `['caching']`.
- `path` in section/root metas is resolved against `basePath`; do not prefix it yourself.
- Top-level `header` items do not inherit from the sidebar. Define them explicitly if you want parity.
- Root `meta.json5` `sections` controls both order and _presence_ — omit a section to hide it from the sidebar index.

## Reference

- `node_modules/@pagesmith/docs/REFERENCE.md`
- `node_modules/@pagesmith/docs/schemas/docs-root-meta.schema.json`
- `node_modules/@pagesmith/docs/schemas/docs-section-meta.schema.json`
- `./references/docs-guidelines.md`