Navigation Model

Nexus Docs does not read a mkdocs.yml nav tree at runtime. It builds navigation from the content file tree plus each page's frontmatter.

That makes navigation git-friendly: moving a file changes its URL and section, while frontmatter controls labels, sorting, visibility, and access behavior.

Loader input

The loader scans content/ recursively and reads every .md and .mdx file.

content/
  getting-started.md
  authoring/
    index.mdx
    frontmatter.md
    navigation.md
    headers.md
  rendering/
    index.mdx
    components.mdx

Each file is transformed into a document record:

Slug rules

The route /docs/[...slug] looks for these candidates, in order:

content/<slug>.md
content/<slug>.mdx
content/<slug>/index.md
content/<slug>/index.mdx

Menu building pipeline

buildNavTree() receives all document metadata and then:

1. Removes pages with nav_hidden: true.
2. Removes draft pages unless showDrafts is enabled for an admin.
3. Removes the empty root slug from the sidebar.
4. Checks ACL and hides private unauthorized pages.
5. Sorts remaining pages by nav_order, then by title.
6. Detects pages that are parents of other pages.
7. Treats parent pages as section nodes with children.
8. Adds leaf pages under their nearest section.
9. Creates implicit section nodes when a folder has children but no index page.

How a MkDocs nav maps to Nexus Docs

In MkDocs you might write:

nav:
  - Getting Started: getting-started.md
  - Authoring:
      - Overview: authoring/index.md
      - Frontmatter: authoring/frontmatter.md
      - Navigation: authoring/navigation.md
      - Headers: authoring/headers.md

In Nexus Docs, express the same structure through files and frontmatter:

content/
  getting-started.md          # title: "Getting Started", nav_order: 1
  authoring/
    index.mdx                 # title: "Authoring Docs", nav_order: 2
    frontmatter.md            # title: "Frontmatter Reference", nav_order: 1
    navigation.md             # title: "Navigation Model", nav_order: 2
    headers.md                # title: "MkDocs Headers and Headings", nav_order: 3

The folder creates hierarchy. title supplies the menu label. nav_order supplies the order.

See MkDocs Headers and Headings for page-level YAML headers, visible Markdown headings, anchors, and table-of-contents behavior.

Menu examples

Flat menu

Use top-level files when the documentation set is small:

content/
  getting-started.md    # nav_order: 1
  seo.md                # nav_order: 2
  operations.md         # nav_order: 3

Rendered menu:

Getting Started
Modern SEO Ready
Operations

Section with children

Use a folder with an index file when a topic needs multiple pages:

content/
  integrations/
    index.mdx           # title: "Integrations", nav_order: 6
    gitlab.md           # title: "GitLab Automatic Integration", nav_order: 1

Rendered menu:

Integrations
  GitLab Automatic Integration

Deeply nested menu

Nested sections work the same way:

content/
  guides/
    index.md            # title: "Guides"
    deployment/
      index.md          # title: "Deployment"
      docker.md         # title: "Docker"
      bare-metal.md     # title: "Bare Metal"

Rendered menu:

Guides
  Deployment
    Docker
    Bare Metal

Hidden helper page

Use nav_hidden: true when a page should be linkable but not part of the menu:

---
title: "Migration Notes"
summary: "Notes linked from release pages."
access_tier: public
product: platform
status: published
owner: maintainer
nav_hidden: true
---

Hidden pages are still routable if the URL is known.

Locked menu item

A protected page can appear in navigation with a lock icon:

---
title: "Customer Configuration"
summary: "Configuration for licensed customers."
access_tier: client
product: nexus/customer-portal
status: published
owner: maintainer
---

Unauthorized users see a locked page for protected tiers. Unauthorized private tiers are hidden instead.

Section index pages

If content/authoring/index.mdx exists, the authoring section gets a clickable item:

Authoring Docs -> /docs/authoring
  Frontmatter Reference -> /docs/authoring/frontmatter
  Navigation Model -> /docs/authoring/navigation
  MkDocs Headers and Headings -> /docs/authoring/headers

If the folder has no index page, the nav builder creates an implicit non-clickable section label from the folder name:

authoring
  Frontmatter Reference
  Navigation Model

Prefer index pages for top-level sections so users have a landing page and breadcrumbs have a meaningful target.

Scoped sidebars

The full nav tree is narrowed by getScopedNav() for document pages. If the current path is under a section, the sidebar shows the nearest section with children instead of the entire site tree.

For example, when viewing:

/docs/authoring/navigation

the sidebar is scoped to:

Authoring Docs
  Frontmatter Reference
  Navigation Model
  MkDocs Headers and Headings

For deeper nesting, a parent back-link is inserted at the top.

Access-aware navigation

Navigation uses the same ACL logic as the page renderer:

• Public pages are shown to everyone.
• Protected pages can be shown as locked links.
• Private unauthorized pages are omitted.
• Draft pages are hidden unless the viewer is an admin.

This means the menu is not just a static table of contents. It is built for the current viewer.