Configure Site Navigation
Learn how to organize pages, define URLs, and control navigation with nav.yml.
CamelMind uses a single file—nav/nav.yml—to define your site's navigation.
Unlike many documentation frameworks, CamelMind does not generate navigation or URLs from your folder structure. Instead, nav.yml is the source of truth for:
- Which pages appear in the sidebar
- The order they appear in
- The URL of every page
- Which users can access each page
This gives you complete control over your documentation without having to move or rename files.
How navigation works
Each page in your site is defined by a navigation entry.
nav:
- label: "Getting Started"
dropdown: true
items:
- label: "Overview"
slug: /getting-started/overview
file: content/getting-started/overview.mdx
roles: []
- label: "Installation"
slug: /getting-started/installation
file: content/getting-started/installation.mdx
roles: []
Each entry connects a public URL to an MDX file.
URL ↓ /getting-started/overview nav.yml ↓ content/getting-started/overview.mdx
Navigation entry
Every page includes four fields.
| Field | Required | Description |
|---|---|---|
label | Yes | Display name shown in the sidebar and navigation. |
slug | Yes | The public URL for the page. |
file | Yes | Path to the MDX file. |
roles | Yes | Roles allowed to access the page. Use [] for public pages. |
Organize pages however you like
The location of a file has no effect on its URL.
For example:
- label: Overview
slug: /overview
file: content/archive/v2/introduction.mdx
roles: []
The page is served at /overview even though the file lives deep inside your project.
This makes it easy to reorganize your content without changing links.
Reuse the same page
A single MDX file can appear in multiple places throughout your documentation.
- label: User Guide
slug: /guides/user-guide
file: content/shared/user-guide.mdx
roles: []
- label: Administrator Guide
slug: /admin/user-guide
file: content/shared/user-guide.mdx
roles: [admin]
This is useful when different audiences need access to the same content through different navigation paths.
Create navigation groups
Top-level entries become navigation groups.
nav:
- label: Platform
dropdown: true
items:
- label: Architecture
slug: /platform/architecture
file: content/platform/architecture.mdx
roles: []
- label: Security
slug: /platform/security
file: content/platform/security.mdx
roles: []
When a visitor opens any page in the group, the corresponding sidebar is displayed automatically.
Think of each top-level group as a section of your documentation, such as Getting Started, Guides, or Reference.
Add sidebar categories
Large navigation groups can be divided into visual categories using section.
items:
- label: "Getting Started"
slug: /getting-started/overview
file: content/getting-started/overview.mdx
roles: []
section:
- label: "Installation"
slug: /getting-started/installation
file: content/getting-started/installation.mdx
roles: []
- label: "Project Structure"
slug: /getting-started/project-structure
file: content/getting-started/project-structure.mdx
roles: []
The parent entry (Getting Started) is displayed as an all-caps section header in the sidebar, with its section items listed beneath it. The parent entry is also a real documentation page. It must define its own slug, file, and roles, and typically serves as an overview or landing page for that section.
Nest pages with children
Any entry—whether it's a top-level item, a section item, or another children item—can have a children array to make it a collapsible row in the sidebar.
- label: "Deployment"
slug: /guides/deployment
file: content/guides/deployment.mdx
roles: []
children:
- label: "Docker"
slug: /guides/deployment/docker
file: content/guides/deployment/docker.mdx
roles: []
- label: "Vercel"
slug: /guides/deployment/vercel
file: content/guides/deployment/vercel.mdx
roles: []
Unlike section, children doesn't add an all-caps category label—the parent entry itself becomes a clickable row with a chevron that expands to reveal its children. children can also nest inside children for additional levels of indentation.
Full schema examples
nav:
# ============================================================================
# Top-level navigation
# ============================================================================
# A top-level entry without `dropdown: true` renders as a direct link in the
# top navigation.
#
# Result:
# Top Nav
# ├── Home
#
- label: "Home"
slug: /home
file: content/home.mdx
roles: []
# ============================================================================
# Navigation group
# ============================================================================
# Setting `dropdown: true` creates a navigation group.
#
# Since `noDropdown` is not enabled, this renders as a dropdown menu in the
# top navigation. Each item below appears in the dropdown.
#
# Result:
# Top Nav
# ├── Guides ▼
# │ ├── Getting Started
# │ └── Deployment
#
- label: "Guides"
dropdown: true
items:
# ------------------------------------------------------------------------
# Section page
# ------------------------------------------------------------------------
# This is BOTH:
#
# • A page (users can visit it)
# • A section header in the sidebar
#
# Because it contains a `section`, CamelMind renders this entry as an
# ALL-CAPS section heading in the sidebar.
#
# Result:
#
# GETTING STARTED
# Installation
# Configuration
#
# Unlike a display-only category, this entry must define:
#
# • slug
# • file
# • roles
#
# It's typically used as an overview page for the section.
#
- label: "Getting Started"
slug: /guides/getting-started/overview
file: content/guides/getting-started/overview.mdx
roles: []
section:
# Standard page within the section.
# Renders as a normal sidebar link.
- label: "Installation"
slug: /guides/getting-started/installation
file: content/guides/getting-started/installation.mdx
roles: []
# Sidebar group
#
# Because this entry contains `children`, it becomes a collapsible
# group instead of a simple link.
#
# Result:
#
# Configuration ▼
# Environment Variables
# Feature Flags
#
- label: "Configuration"
slug: /guides/getting-started/configuration
file: content/guides/getting-started/configuration.mdx
roles: []
children:
# Child pages are nested beneath their parent.
- label: "Environment Variables"
slug: /guides/getting-started/configuration/env-vars
file: content/guides/getting-started/configuration/env-vars.mdx
roles: []
- label: "Feature Flags"
slug: /guides/getting-started/configuration/feature-flags
file: content/guides/getting-started/configuration/feature-flags.mdx
roles: []
# ------------------------------------------------------------------------
# Sidebar group (without a section)
# ------------------------------------------------------------------------
# This entry contains `children` but no `section`.
#
# Unlike "Getting Started", it does NOT create an ALL-CAPS section
# heading. Instead, this page itself becomes the collapsible sidebar row.
#
# Result:
#
# Deployment ▼
# Docker
# Vercel
#
- label: "Deployment"
slug: /guides/deployment
file: content/guides/deployment.mdx
roles: []
children:
- label: "Docker"
slug: /guides/deployment/docker
file: content/guides/deployment/docker.mdx
roles: []
- label: "Vercel"
slug: /guides/deployment/vercel
file: content/guides/deployment/vercel.mdx
roles: []
# ============================================================================
# Direct top-level link
# ============================================================================
# `dropdown: true` normally creates a dropdown menu.
#
# Setting `noDropdown: true` changes the behavior so this renders as a direct
# top navigation link instead.
#
# The link uses this entry's own `slug`, while the `items` are still available
# to build the sidebar for pages within this section.
#
# Result:
#
# Top Nav
# ├── Reference
#
- label: "Reference"
dropdown: true
noDropdown: true
slug: /reference/overview
items:
- label: "API"
slug: /reference/api
file: content/reference/api.mdx
roles: []
Setting noDropdown: true on every group means nothing ever opens as a dropdown button in the top nav—each group is a direct link, and all the grouping happens in the sidebar via section and children.
nav:
# ============================================================================
# Single documentation section
# ============================================================================
# This configuration creates a single top-level documentation section.
#
# `noDropdown: true` renders "Documentation" as a direct link in the top
# navigation instead of a dropdown menu. The pages defined below build the
# sidebar for this section.
#
# Result:
#
# Top Nav
# ├── Documentation
#
- label: "Documentation"
dropdown: false
noDropdown: true
items:
# ------------------------------------------------------------------------
# Section landing page
# ------------------------------------------------------------------------
# This entry serves two purposes:
#
# • It's the landing page for the Documentation section.
# • It becomes the ALL-CAPS section heading in the sidebar.
#
# Because it contains a `section`, CamelMind renders this entry as a
# sidebar section header while still allowing users to visit the page.
#
# Result:
#
# OVERVIEW
# Quick Start
# Advanced
#
# Unlike a display-only category, this page must define:
#
# • slug
# • file
# • roles
#
# It's typically used as an introduction or overview of the section.
#
- label: "Overview"
slug: /docs/overview
file: content/docs/overview.mdx
roles: []
section:
# Standard documentation page.
# Appears as a normal sidebar link.
- label: "Quick Start"
slug: /docs/quick-start
file: content/docs/quick-start.mdx
roles: []
# Sidebar group
#
# Because this entry contains `children`, CamelMind renders it as a
# collapsible group in the sidebar.
#
# Result:
#
# Advanced ▼
# Caching
# Scaling
#
- label: "Advanced"
slug: /docs/advanced
file: content/docs/advanced.mdx
roles: []
children:
# Child pages appear nested beneath "Advanced".
- label: "Caching"
slug: /docs/advanced/caching
file: content/docs/advanced/caching.mdx
roles: []
- label: "Scaling"
slug: /docs/advanced/scaling
file: content/docs/advanced/scaling.mdx
roles: []
Documentation renders in the top nav as a direct link to /docs/overview (its first visible item's slug, since the group itself has no slug). Its sidebar still shows the Overview category with Quick Start as a plain link and Advanced as a collapsible row.
Without any section fields, the sidebar has no all-caps category headers—every item is either a plain link or a collapsible row.
nav:
- label: "Guides"
dropdown: true
items:
- label: "Writing Content"
slug: /guides/writing-content
file: content/guides/writing-content.mdx
roles: []
children:
- label: "Markdown Basics"
slug: /guides/writing-content/markdown-basics
file: content/guides/writing-content/markdown-basics.mdx
roles: []
- label: "Frontmatter"
slug: /guides/writing-content/frontmatter
file: content/guides/writing-content/frontmatter.mdx
roles: []
In the top nav, Guides is a dropdown listing Writing Content. In the sidebar, Writing Content has no category header above it—it's simply a collapsible row that expands to show Markdown Basics and Frontmatter.
Restrict access with roles
The roles field determines who can view and access a page.
| Roles | Access |
|---|---|
[] | Public |
["admin"] | Administrators only |
["vendor","admin"] | Vendors or administrators |
Pages that users don't have permission to access are:
- Hidden from navigation
- Blocked from direct URL access
See Authentication & RBAC for configuration details.