Directory Structure

A well-organized directory structure makes your documentation easier to maintain and navigate.

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"]

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

"pages": ["introduction", "guides/quickstart", "reference/api"]

Naming Conventions

Special Directories

images/

Store images, logos, and favicons:

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

Reference in docs.json:

{
  "logo": {
    "light": "/images/logo-light.svg",
    "dark": "/images/logo-dark.svg"
  },
  "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:

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

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?