docs.json Reference

The docs.json file is the central configuration for your Jamdesk documentation site.

Required Fields

name

Type: string (required)

Your documentation site's name. Displayed in the header and browser tab.

{ "name": "Acme API Docs" }

theme

Type: "jam" | "nebula" | "pulsar" (required)

colors

Type: object (required)

{
  "colors": {
    "primary": "#635BFF",
    "light": "#7C75FF",
    "dark": "#4F46E5"
  }
}

Branding

favicon

Type: string

Path to your favicon file (SVG recommended).

{ "favicon": "/images/favicon.svg" }

logo

Type: object

{
  "logo": {
    "light": "/images/logo-light.webp",
    "dark": "/images/logo-dark.webp",
    "href": "https://yoursite.com"
  }
}

OpenAPI

api.openapi

Type: string | string[]

List the OpenAPI 3.x spec files you want Jamdesk to validate and use for endpoint pages. Use paths relative to your docs.json.

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

Once configured, you can generate endpoint pages by adding an openapi field in a page’s frontmatter:

---
title: Create Ticket
openapi: /openapi/api.yaml POST /tickets
---

If you only have one spec listed, you can also use the short format:

---
title: Create Ticket
openapi: POST /tickets
---

See OpenAPI Example for a live endpoint page and Directory Structure for file placement.

If your site is multilingual, drop a <spec>.<lang>.<ext> file next to each source spec (e.g., openapi/api.fr.yaml) and Jamdesk serves it on that language's URLs. See Translating OpenAPI Specs.

api.examples.languages

Type: string[] Default: ["curl", "python", "javascript"]

Choose which programming languages appear in auto-generated API code examples on openapi: pages. The array order determines tab display order, and the first language is selected by default.

Supported values: curl, bash, python, javascript, go, ruby, csharp, java, rust, php

{
  "api": {
    "examples": {
      "languages": ["curl", "python", "javascript", "go", "ruby", "csharp", "java", "rust", "php"]
    }
  }
}

{
  "api": {
    "examples": {
      "languages": ["python", "javascript", "go"]
    }
  }
}

api.examples.defaults

Type: "required" | "all" Default: "all"

Control which parameters appear in auto-generated code examples.

{
  "api": {
    "examples": {
      "defaults": "required"
    }
  }
}

api.examples.prefill

Type: boolean Default: false

When true, the API Playground pre-fills parameter fields with example values from your OpenAPI spec.

{
  "api": {
    "examples": {
      "prefill": true
    }
  }
}

api.playground.display

Type: "interactive" | "simple" | "none" Default: "interactive"

Controls the API Playground on endpoint pages. A "Try it" button appears on every openapi: and api: page by default.

{
  "api": {
    "playground": {
      "display": "interactive"
    }
  }
}

See API Playground for usage details and per-page overrides.

api.mdx.auth.method

Type: "bearer" | "basic" | "key" | "cobo"

Authentication method used in auto-generated code examples. When set, examples include the appropriate authentication header.

{
  "api": {
    "mdx": {
      "auth": {
        "method": "bearer"
      }
    }
  }
}

api.mdx.auth.name

Type: string

Custom header name for key-based authentication. Only used when api.mdx.auth.method is "key".

{
  "api": {
    "mdx": {
      "auth": {
        "method": "key",
        "name": "X-API-Key"
      }
    }
  }
}

Navigation

tabsPosition

Type: "top" | "left"

Controls where navigation tabs are displayed.

Default value depends on your theme:

{ "tabsPosition": "left" }

anchors

Type: array

External links that appear at the top of the sidebar on all pages.

{
  "anchors": [
    { "name": "Blog", "href": "https://blog.example.com", "icon": "newspaper" }
  ]
}

navigation (structure)

Type: object

The navigation structure for your documentation. See Navigation for detailed documentation.

Pages can be strings (title auto-generated from filename) or objects with a custom title:

"pages": [
  "introduction",
  { "page": "content/mdx-basics", "title": "MDX Basics" }
]

{
  "navigation": {
    "tabs": [
      {
        "tab": "Docs",
        "icon": "book-open",
        "groups": [
          {
            "group": "Getting Started",
            "pages": ["introduction", "quickstart"]
          }
        ]
      }
    ]
  }
}

Navbar & Footer

navbar

Type: object

{
  "navbar": {
    "links": [
      {
        "label": "Blog",
        "labels": { "fr": "Blog", "es": "Blog" },
        "href": "/blog"
      },
      {
        "label": "Pricing",
        "labels": { "fr": "Tarifs", "es": "Precios" },
        "href": "/pricing"
      }
    ],
    "primary": {
      "type": "button",
      "label": "Dashboard",
      "labels": { "fr": "Tableau de bord", "es": "Panel" },
      "href": "https://app.example.com"
    }
  }
}

footer

Type: object

Configure the page footer with social links and custom link columns.

{
  "footer": {
    "socials": {
      "github": "https://github.com/yourorg",
      "x": "https://x.com/yourhandle",
      "discord": "https://discord.gg/yourserver"
    },
    "links": [
      {
        "header": "Resources",
        "items": [
          { "label": "Blog", "href": "https://example.com/blog" },
          { "label": "Changelog", "href": "/changelog" }
        ]
      }
    ]
  }
}

Supported social platforms: github, x, twitter, linkedin, discord, slack, youtube, instagram, facebook, reddit, telegram, bluesky, threads, medium, hacker-news, website

Styling

styling.latex

Type: boolean

Enable LaTeX math rendering with KaTeX. When enabled, you can use $...$ for inline math and $$...$$ for block equations.

{
  "styling": {
    "latex": true
  }
}

See Math & LaTeX for usage details.

styling.js

Type: string | string[]

Custom JavaScript file(s) to include on every page. Paths are relative to your docs directory and must start with /.

{
  "styling": {
    "js": "/script.js"
  }
}

Pass an array for multiple files:

{
  "styling": {
    "js": ["/chat.js", "/analytics.js"]
  }
}

Without this field, Jamdesk auto-detects .js files in your project root. See Custom JavaScript for details.

Chat

chat

Type: object (optional)

Configure the built-in AI chat assistant. Chat is enabled by default on all sites; you only need this field to customize starter questions or disable it.

{
  "chat": {
    "starterQuestions": [
      "How do I get started?",
      "What API endpoints are available?"
    ]
  }
}

See AI Chat for details on how chat works and what visitors see.

AI Actions Menu

contextual

Type: object (optional)

Configure the AI Actions dropdown that appears on every page. Enabled by default with all options; you only need this field to customize which options appear or disable it.

Built-in option keys: copy, view, chatgpt, claude, perplexity, gemini, mcp, cursor, vscode

{
  "contextual": {
    "options": ["copy", "claude", "mcp", "cursor"]
  }
}

Add custom options alongside built-in ones:

{
  "contextual": {
    "options": [
      "copy",
      "claude",
      {
        "title": "Ask on Discord",
        "description": "Get help from the community",
        "icon": "discord",
        "href": "https://discord.gg/your-server"
      }
    ]
  }
}

See AI Actions Menu for the full list of options and custom option format.

Spellcheck

spellcheck

Type: object (optional)

Configure the jamdesk spellcheck CLI command. You only need this field to add project-specific words to the ignore list.

{
  "spellcheck": {
    "ignore": ["Acme", "kubectl", "Terraform"]
  }
}

The CLI includes 180+ built-in tech terms (API, GraphQL, Kubernetes, React, etc.) and automatically ignores your project name from the name field. Only add words specific to your project.

See CLI Overview: Spellcheck for usage details and interactive fix mode.

Images

images.convertToWebp

Type: boolean (optional, default false)

Enable automatic WebP conversion for PNG and JPG assets during builds. Converted files are usually 60-80% smaller than the originals with no visible quality loss. References in your MDX, custom CSS, custom JS, and docs.json are rewritten automatically, so you don't change any paths.

Favicons, og:image, and twitter:image stay in their original format. Not every social crawler or email client renders WebP reliably, and a broken preview card is worse than a slightly larger JPG.

{
  "images": {
    "convertToWebp": true
  }
}

See Automatic Image Conversion for what gets converted, how caching works, and the build progress indicator.

Access Control

auth.password

Type: object (optional)

Opt in to shared-password protection for your site. Declarative config only. You still set the actual passphrase in the dashboard after the next build runs.

Set auth.password.enabled: true to lock the whole site, or list paths under auth.password.private[] to protect just those pages. Both trigger the same dashboard password prompt on the next build.

{
  "auth": {
    "password": {
      "enabled": true,
      "hint": "Ask your account manager",
      "public": ["/marketing/**", "/changelog"]
    }
  }
}

See Password Protection for the full walkthrough, including the dashboard flow and how frontmatter public: true / private: true interact with these arrays.

Full Example

{
  "$schema": "https://jamdesk.com/docs.json",
  "name": "Acme Documentation",
  "description": "Learn how to use Acme",
  "theme": "jam",
  "colors": {
    "primary": "#635BFF"
  },
  "favicon": "/images/favicon.svg",
  "logo": {
    "light": "/images/logo-light.webp",
    "dark": "/images/logo-dark.webp"
  },
  "api": {
    "openapi": ["/openapi/api.yaml"],
    "playground": {
      "display": "interactive"
    },
    "examples": {
      "languages": ["curl", "python", "javascript"],
      "prefill": true
    }
  },
  "styling": {
    "latex": true,
    "js": "/script.js"
  },
  "chat": {
    "starterQuestions": ["How do I get started?", "What endpoints are available?"]
  },
  "contextual": {
    "options": ["copy", "claude", "chatgpt", "mcp", "cursor"]
  },
  "spellcheck": {
    "ignore": ["Acme"]
  },
  "anchors": [
    { "name": "Blog", "href": "https://blog.acme.com", "icon": "newspaper" }
  ],
  "navbar": {
    "links": [
      { "label": "Support", "href": "/support" }
    ],
    "primary": {
      "type": "button",
      "label": "Dashboard",
      "href": "https://app.acme.com"
    }
  },
  "navigation": {
    "tabs": [
      {
        "tab": "Docs",
        "icon": "book-open",
        "groups": [
          {
            "group": "Get Started",
            "pages": ["introduction", "quickstart"]
          }
        ]
      },
      {
        "tab": "API Reference",
        "icon": "code",
        "groups": [
          {
            "group": "Endpoints",
            "pages": ["api/users", "api/posts"]
          }
        ]
      }
    ]
  }
}

What's Next?