> For a complete documentation index, see /llms.txt. To read any public page as Markdown, append .md to the URL. 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. ```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 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: ```yaml - 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. ```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 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. ```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: [] ``` 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. ```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 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. ```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` 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 === "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 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: [] ``` === "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 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](/features/auth-rbac) for configuration details.