---
title: Directory Structure
description: A clean docs directory makes navigation, builds, and collaboration easier. Follow it when configuring new projects or onboarding additional repositories.
---

> **For AI agents:** the complete documentation index is at [llms.txt](/docs/llms.txt). Append `.md` to any page URL for its markdown version.

A clean directory structure makes navigation, builds, and collaboration easier.

## Minimal Structure

The simplest Jamdesk project needs just two files:

```bash
my-docs/
├── docs.json           # Configuration
└── introduction.mdx    # Your first page
```

## Recommended Structure

For larger documentation sites, organize pages into directories:

```bash
my-docs/
├── docs.json
├── introduction.mdx
├── quickstart.mdx
│
├── guides/
│   ├── getting-started.mdx
│   ├── authentication.mdx
│   └── deployment.mdx
│
├── api-reference/
│   ├── overview.mdx
│   ├── endpoints/
│   │   ├── users.mdx
│   │   └── projects.mdx
│   └── webhooks.mdx
│
├── images/
│   ├── logo.svg
│   ├── favicon.svg
│   └── screenshots/
│       └── dashboard.png
│
└── snippets/
    └── api-base-url.mdx
```

<Tip>
The [Jamdesk documentation repo](https://github.com/jamdesk/jamdesk-docs) is a production example of this structure — two tabs, 120+ pages, OpenAPI specs, and custom scripts.
</Tip>

## Required Files

### docs.json

The configuration file that defines your site. Must be in the root of your docs directory (or the path specified in project settings).

```json docs.json
{
  "$schema": "https://jamdesk.com/docs.json",
  "name": "My Documentation",
  "theme": "jam",
  "colors": {
    "primary": "#635BFF"
  },
  "navigation": {
    "groups": [
      {
        "group": "Getting Started",
        "pages": ["introduction", "quickstart"]
      }
    ]
  }
}
```

See [docs.json Reference](/config/docs-json-reference) for all options.

## Page Organization

### Flat vs Nested

Choose based on your documentation size:

<Tabs>
  <Tab title="Flat (< 20 pages)">
    Keep all pages in the root:

    ```bash
    docs/
    ├── docs.json
    ├── introduction.mdx
    ├── installation.mdx
    ├── configuration.mdx
    └── troubleshooting.mdx
    ```

    Reference pages directly in navigation:

    ```json
    "pages": ["introduction", "installation"]
    ```
  </Tab>
  <Tab title="Nested (20+ pages)">
    Group related pages in directories:

    ```bash
    docs/
    ├── docs.json
    ├── introduction.mdx
    ├── guides/
    │   ├── quickstart.mdx
    │   └── advanced.mdx
    └── reference/
        ├── api.mdx
        └── cli.mdx
    ```

    Include the directory in the path:

    ```json
    "pages": ["introduction", "guides/quickstart", "reference/api"]
    ```
  </Tab>
</Tabs>

### Naming Conventions

| Convention | Example | URL |
|------------|---------|-----|
| Lowercase | `getting-started.mdx` | `/getting-started` |
| Kebab-case | `api-reference.mdx` | `/api-reference` |
| Directories | `guides/auth.mdx` | `/guides/auth` |

<Warning>
Avoid spaces and special characters in filenames. Use hyphens to separate words.
</Warning>

## Special Directories

### images/

Store images, logos, and favicons:

```bash
images/
├── logo-light.webp     # Light mode logo
├── logo-dark.webp      # Dark mode logo
├── favicon.svg         # Browser favicon
└── screenshots/        # Documentation screenshots
    └── dashboard.png
```

Reference in docs.json:

```json docs.json
{
  "logo": {
    "light": "/images/logo-light.webp",
    "dark": "/images/logo-dark.webp"
  },
  "favicon": "/images/favicon.svg"
}
```

### snippets/

Reusable content blocks:

```bash
snippets/
├── api-base-url.mdx
└── auth-header.mdx
```

Include in pages:

```mdx
<Snippet file="api-base-url.mdx" />
```

### openapi/

OpenAPI specification files for API documentation:

```bash
openapi/
├── api.yaml
└── webhooks.yaml
```

Reference in docs.json:

```json docs.json
{
  "api": {
    "openapi": ["/openapi/api.yaml"]
  }
}
```

For a live example, see [OpenAPI Example](/api-reference/openapi-example).

#### Language-specific spec files

For multi-language docs sites, add translated spec files next to the source with a language-code infix:

```bash
openapi/
├── api.yaml
├── api.fr.yaml
├── api.es.yaml
└── api.zh.yaml
```

Jamdesk automatically serves the correct spec when a page is rendered under a language prefix (`/fr/…`, `/es/…`, etc.). See [Multi-Language Support → Translating OpenAPI Specs](/setup/languages#translating-openapi-specs) for the full rules on what to translate and what to keep identical.

## Files to Ignore

Create a `.gitignore` to exclude build artifacts:

```bash
.jamdesk/
node_modules/
.DS_Store
*.log
```

The `.jamdesk/` directory contains local development cache and should not be committed.

## What's Next?

<Columns cols={2}>
  <Card title="Monorepo Support" icon="folders" href="/setup/monorepo-support">
    Configure docs path for monorepos
  </Card>
  <Card title="docs.json Reference" icon="gear" href="/config/docs-json-reference">
    All configuration options
  </Card>
</Columns>