Configure Site Navigation
Configure site navigation in nav.yml using label, slug, file, roles, dropdown, noDropdown, section, and children.
CamelMind uses a single file—nav/nav.yml—to define your site's navigation.
Unlike other 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 nav.yml defines page navigation
A navigation entry defines each page in your site.
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 fields: label, slug, file, and roles
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. |
How file location affects page URLs
The location of a file has no effect on its URL.
For example:
- label: Overview
slug: /overview
file: content/archive/v2/introduction.mdx
roles: []
Your server serves the page at /overview even though the file lives deep inside your project. This makes it easy to reorganize your content without changing links.
How to reuse one MDX page in multiple navigation paths
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 top-level navigation groups with dropdown
Use dropdown: true on a top-level nav.yml entry to create a navigation group in the top navigation.
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: []
Opening any page in the group automatically displays the corresponding sidebar.
Think of each top-level group as a section of your documentation, such as Getting Started, Guides, or Reference.
How noDropdown changes top navigation behavior
Set noDropdown: true on a navigation group to render the group as a direct top-navigation link instead of a dropdown menu. The group's items still define the sidebar navigation for pages in that section.
How to create sidebar categories with section
Use the section field to group navigation entries under an all-caps category heading in the sidebar.
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 sidebar displays the parent entry (Getting Started) as an all-caps section header, listing its section items 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.
How to create collapsible sidebar groups with children
Use children to create a collapsible sidebar row. Unlike section, children does not create an all-caps category heading.
- 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 does not 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.
Complete nav.yml 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 is 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 is a collapsible row that expands to show Markdown Basics and Frontmatter.
How to restrict navigation pages with roles
Use the roles field in a nav.yml entry to control which users can view and access a page. Use roles: [] for a public page.
| Roles | Access |
|---|---|
[] | Public |
["admin"] | Administrators only |
["vendor","admin"] | Vendors or administrators |
Pages that users do not have permission to access are:
- Hidden from navigation
- Blocked from direct URL access
See Authentication & RBAC for configuration details.