---
title: Project Structure
description: A tour of the folders and files in a CamelMind site — what each one does and which ones you'll actually edit.
---

Every CamelMind project follows the same directory structure. Most of your work will happen in certain folders, while the rest powers the framework behind the scenes.

This guide explains what each folder is for and when you'll need to edit it.

```text
my-docs/
├── app/                      # Next.js routes and rendering
├── components/               # UI and MDX components
├── content/                  # Documentation pages
├── lib/                      # Internal utilities
├── nav/
│   └── nav.yml               # Sidebar navigation
├── public/                   # Images and downloads
├── scripts/                  # Build utilities
├── camelmind.config.ts       # Site configuration
├── versions.yml              # Documentation versions
├── next.config.ts            # Next.js configuration
├── .env.example              # Configuration template; duplicate to .env.local before running
├── package.json
└── tsconfig.json
```

<Callout type="tip">

Most documentation work only involves these folders:

| Want to... | Edit |
|------------|------|
| Write documentation | `content/` |
| Organize the sidebar | `nav/nav.yml` |
| Add images or assets | `public/` |
| Change the site title | `camelmind.config.ts` |

</Callout>

---

## CamelMind content directory structure

The CamelMind `content/` directory stores every MDX documentation page for your site structure and authoring workflow.

```text
content/
├── getting-started/
│   └── overview.mdx
├── guides/
│   └── writing-docs.mdx
└── reference/
    └── configuration.mdx
```

Unlike other documentation frameworks, CamelMind does not derive URLs from your folder structure. Define your URLs directly in `nav.yml` to take complete control over your site's navigation.

---

## The nav/nav.yml file

`nav.yml` serves as the single source of truth for your sidebar menu and page URLs. Every entry maps a `slug` (the public URL) to a `file` (the MDX source):

```yaml
nav:
  - label: "Getting Started"
    dropdown: false
    noDropdown: true
    items:
      - label: "Project Structure"
        slug: /getting-started/project-structure
        file: content/getting-started/project-structure.mdx
        roles: []
```

Register every `content/` page here to make it reachable; you can also assign a page to multiple slugs using distinct labels or roles. See [Configure Navigation](/getting-started/navigation) reference for every field.

---

## CamelMind versions.yml file configuration

The CamelMind `versions.yml` configuration file defines all published documentation versions and multi-version site settings.


```yaml
versions:
  - id: "latest"
    label: "Latest"
    stable: true
    nav: nav/nav.yml
```

A fresh scaffold ships with a single `latest` version. Add entries here when you're ready to publish multiple versions side by side.

---

## CamelMind primary configuration file camelmind.config.ts

The `camelmind.config.ts` file acts as the primary configuration blueprint for CamelMind site settings, authentication options, and global properties.


```typescript
const config: CamelMindConfig = {
  title: "My Docs",
  tagline: "Documentation made simple.",
  url: process.env.CAMELMIND_URL ?? "http://localhost:3000",

  contentDir: "content",
  navFile: "nav/nav.yml",
  versionsFile: "versions.yml",

  auth: { enabled: false, requireLogin: false, provider: "dev-mock", /* ... */ },
  links: { github: "https://github.com/you/your-repo" },
  ai: { llmsTxt: { enabled: false, directive: "" } },
}
```

CamelMind reads most secrets and environment-specific values (auth toggles, the site URL) from environment variables in `.env.example` / `.env.local` rather than hardcoding them here.

---

## The CamelMind app/ application directory

The `app/` directory contains the Next.js application routes and logic that power your CamelMind documentation site.

| Path | Purpose |
|---|---|
| `app/[...slug]/page.tsx` | The catch-all route that renders every doc page — resolves the slug against `nav.yml`, loads the MDX file, and applies auth checks |
| `app/api-reference/` | Route for the OpenAPI-powered API reference |
| `app/api/auth/` | Login, logout, and OIDC callback route handlers |
| `app/api/search/` | Full-text search endpoint |
| `app/api/llms/`, `app/llms.txt/` | AI-readable documentation output (`/llms.txt` and `/api/llms`) |
| `app/home/page.tsx` | The homepage |
| `app/layout.tsx` | Root layout — theming, fonts, global providers |
| `app/globals.css` | Global styles (Tailwind) |

<Callout type="warning">
Customizing files in `app/` is an advanced use case. Changes here can be overwritten or need manual reconciliation when you run `camelmind update` — see [Update CamelMind](/getting-started/installation#update-camelmind) for the `--ignore-file` flag if you need to protect a customized file.
</Callout>

---

## CamelMind components directory and React UI modules

The `components/` directory contains all React UI components, layout elements, and custom MDX widgets used throughout your CamelMind site.

- **Site chrome** — `Nav/`, `Sidebar/`, `Toc/`, `Breadcrumbs/`, `PageNav/`, `Search/`, `SectionCards/`, `ApiReference/`, and similar folders render the surrounding site UI (top nav, sidebar, table of contents, search modal).
- **`components/mdx/`** — the components available directly inside your `.mdx` content: `Callout`, `Steps`, `Tabs`, `Details`, `Icon`, `LLMOnly`, and `LLMIgnore`.

See [Use MDX Components](/getting-started/mdx-components) for how to use each one in your content.

---

## The CamelMind lib/ utility directory

The `lib/` directory contains core TypeScript modules responsible for parsing content and navigation in CamelMind.

| File | Responsibility |
|---|---|
| `lib/mdx.ts` | Reads an MDX file, parses frontmatter, extracts the table of contents |
| `lib/nav.ts`, `lib/nav-types.ts` | Parses `nav.yml`, resolves slugs to entries, builds breadcrumbs |
| `lib/versions.ts` | Resolves which version's nav applies to a given URL |
| `lib/config.ts`, `lib/config-types.ts` | Loads and types `camelmind.config.ts` |
| `lib/auth.ts`, `lib/auth-roles.ts`, `lib/auth-providers/` | Session handling and role-based access control |
| `lib/api-reference.ts`, `lib/api-types.ts`, `lib/api-utils.ts` | OpenAPI spec parsing for the API reference |

---

## CamelMind scripts/ build and export utilities

The `scripts/` directory houses standalone automation scripts for generating offline release artifacts in CamelMind.

| Script | Purpose |
|---|---|
| `scripts/build-offline.sh` | Builds a static, ZIP-packaged offline version of the site |
| `scripts/build-search-index.ts` | Pre-generates the search index used by offline builds |
| `scripts/generate-pdfs.ts`, `scripts/generate-master-pdf.ts` | Generate per-page and combined PDF exports |
| `scripts/build-pdf.sh` | Wraps the PDF generation scripts into a single build step |

See [Offline Package and PDF Export](/features/offline-package-and-pdf-export) for how these fit into a release workflow.

---

## CamelMind root configuration files

The following table outlines the purpose of each root configuration file in your CamelMind project:

| File | Purpose |
|---|---|
| `package.json` | Project dependencies and CLI script runners (`dev`, `build`, `start`, `lint`). |
| `next.config.ts` | Next.js compilation options, security headers, and static export toggles. |
| `tsconfig.json` | Global TypeScript compiler settings. |
| `eslint.config.mjs` | Project code quality and linting rules. |
| `.env.example` | Local environment configuration blueprint. Duplicate to `.env.local` to start. |
| `vercel.json` | Optimized deployment configurations specific to Vercel. |

<Callout type="note">
After running `camelmind update`, you may see a `.camelmind-update-backup/` folder appear — it holds a timestamped copy of any files the updater overwrote. It's safe to delete once you've confirmed the update looks correct.
</Callout>

---

## CamelMind next steps and related resources

Explore these resources to continue building and customizing your CamelMind documentation site.

| Goal | Where to go |
|---|---|
| Write and organize pages | [Writing Content](/getting-started/writing-content) |
| Use Callout, Steps, Tabs, and more | [MDX Components](/getting-started/mdx-components) |
| Change the sidebar and URLs | [Configure Navigation](/getting-started/navigation) |
| Publish multiple doc versions | [Configure Multiple Documentation Sites](/getting-started/multiple-doc-sites) |
| Gate pages by user role | [Auth and RBAC](/features/auth-rbac) |