Navigation

The file can take three shapes. Use the smallest one that fits.

Groups, the common case and the shape this site uses: one list of groups and pages, as above.

Tabs: several labelled sections, each with its own groups. The sidebar shows each tab's label above its groups.

{
  "tabs": [
    {
      "label": "Guides",
      "groups": [
        { "group": "Get started", "pages": ["index", "installation"] }
      ]
    },
    {
      "label": "API",
      "groups": [
        { "group": "Resources", "pages": ["api/orders", "api/customers"] }
      ]
    }
  ]
}

A bare list, for a small set: pages and groups with nothing around them.

["index", "installation", "configuration", "faq"]

Inside { "groups": [...] } or a tab, you may also write "pages": [...] for entries that sit outside any group. When both are present, the groups entries come first.

The schema also accepts a tab with href instead of groups, as a link in place of a section. The current reader UI shows such a tab's label without the link, so use a link entry inside a group for now.

{
  "groups": [
    {
      "group": "Billing",
      "pages": [
        "billing",
        "billing/invoices",
        { "group": "Webhooks", "collapsed": true, "pages": ["billing/webhooks/events", "billing/webhooks/retries"] }
      ]
    }
  ]
}

A group may be named with label instead of group.

icon takes a Lucide icon name on pages, groups, links and tabs. LaRecipe passes it to the reader UI, but the default sidebar does not draw navigation icons yet.

A page's badge frontmatter shows next to its entry. Pages that changed in the last day carry a small dot until the reader opens them; set the window with ui.fresh_days in the configuration.

The navigation is the same file for everyone, but each reader sees only what they may read. Private pages are left out for readers who cannot open them, and a group with nothing left to show disappears. Entries for pages that do not exist are left out too, and larecipe:validate reports them.

Write each old path as the page path inside the version, as you would in navigation.json. A request for the old path redirects with a 301 to this page, in the same version and language, and a request for the old Markdown twin (hooks.md) redirects to the new twin. The full old URL path, such as /docs/3.x/hooks, matches as well.

LaRecipe looks for redirect_from among the pages of the version and language that was requested, and only among the pages the reader may see, so an old URL never reveals a private page. A page copied into a new version keeps its redirect_from, but a translation needs its own to redirect its old URL.

from is the full path of the old URL: the set's prefix, then the version, then the page (with the language segment for a translation). to is any path or URL, and status defaults to 301 (302, 307 and 308 work too).

On a versioned set, a from without a version applies in every version. { "from": "/docs/setup", "to": "/docs/installation" } sends /docs/3.x/setup to /docs/3.x/installation and /docs/2.x/setup to /docs/2.x/installation: a to inside the set that names no version stays in the reader's version. Write the version in from to redirect one version only.

larecipe:validate reports redirects that loop (redirects.loop) and redirects from a URL a page still lives at (redirects.shadowed). To redirect URLs outside the docs, or a whole old prefix, use your app's routes. Upgrade from v2 shows how this site keeps its LaRecipe 2 URLs working.

Each language uses the version's navigation, with the translated title of every page that has a translation. To change the order or translate the group labels, give the language its own file next to its pages, such as docs/3.x/ar/navigation.json. LaRecipe looks there first, then falls back to the version's file. See languages.

larecipe:navigation:freeze writes the default version's file (--docs-version=2.x for another, --locale=ar for a language's own file, --set= for another doc set), with the $schema pointer and the groups in the order readers see them now. A version that already has a navigation.json is left alone. It works on repository sets; a database set changes its navigation with the update_navigation MCP tool. Read live from this app:

php artisan larecipe:navigation:freeze [--set [SET]] [--docs-version [DOCS-VERSION]] [--locale [LOCALE]] [--dry-run]

Derived navigation lists every page by construction, so it never has orphans.