Directory Structure

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

Minimal Structure

The simplest Jamdesk project needs just two files:

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

Recommended Structure

For larger documentation sites, organize pages into directories:

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

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).

{
  "$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 for all options.

Page Organization

Flat vs Nested

Choose based on your documentation size:

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

"pages": ["introduction", "installation"]

Naming Conventions

Special Directories

images/

Store images, logos, and favicons:

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:

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

snippets/

Reusable content blocks:

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

Include in pages:

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

openapi/

OpenAPI specification files for API documentation:

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

Reference in docs.json:

{
  "api": {
    "openapi": ["/openapi/api.yaml"]
  }
}

For a live example, see OpenAPI Example.

Language-specific spec files

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

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 for the full rules on what to translate and what to keep identical.

Files to Ignore

Create a .gitignore to exclude build artifacts:

.jamdesk/
node_modules/
.DS_Store
*.log

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

What's Next?