--- title: Configure Site Navigation description: 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. ```yaml 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: ```yaml - 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. ```yaml - 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. ```yaml 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`. ```yaml 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. ```yaml - 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 === "Example: every field in one nav.yml" ```yaml 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: [] ``` === "Example: no dropdown menus, with sections and children" 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`. ```yaml 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. === "Example: only children, no sections" Without any `section` fields, the sidebar has no all-caps category headers—every item is either a plain link or a collapsible row. ```yaml 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.