navigation.json

navigation.json is an optional file that overrides the navigation Verto derives from your folder structure. You only need it when you want to change what the file system would do naturally — rename an entry, change its sort position, or hide it — without renaming files or editing their frontmatter. Delete the file and Verto falls back entirely to file-system defaults.

Location

The file lives at the source root:

Schema

A single top-level overrides object. Each key is a slug path relative to the content root (no file extension); each value may set any of title, order, or hidden:

{
  "overrides": {
    "docs": { "title": "Docs", "order": 1 },
    "docs/getting-started": { "title": "Getting Started", "order": 1 },
    "docs/core-concepts": { "title": "Core Concepts", "order": 2 },
    "docs/reference": { "title": "Reference", "order": 6 },
    "drafts": { "hidden": true },
    "notes/2024-old-slug": { "title": "A Friendlier Name" }
  }
}

Fields

Every field is optional. Anything you omit falls through to the file-system / frontmatter value.

How keys work

Keys are slugs, not file paths:

• No extension. Use docs/getting-started/introduction, not …/introduction.mdx.
• Directories use their slug. To rename a group, key the directory: docs/getting-started, not the files inside it.
• No href field. URLs are always derived from the file path — you can't remap a URL here, only relabel/reorder/hide it.

Behavior and fallbacks

• The file is optional. If it's absent, unreadable, not valid JSON, or missing the overrides key, Verto silently uses file-system defaults — a malformed navigation.json never breaks a build.
• Overrides are applied to every matching node as the tree is assembled, so a directory override (e.g. hidden) cascades to its descendants in listings.

Examples

Rename and reorder the top-level sections:

{
  "overrides": {
    "docs": { "title": "Documentation", "order": 1 },
    "blog": { "title": "Writing", "order": 2 }
  }
}

Hide a whole working directory from the published site:

{ "overrides": { "scratch": { "hidden": true } } }

Give a single file a nicer label without renaming it:

{ "overrides": { "docs/faq": { "title": "Frequently Asked Questions" } } }

Related

• Navigation — the file-system model these overrides sit on top of
• Frontmatter — set title / order / hidden per file instead
• Environment Variables — where the source root (and thus this file) lives for remote sources