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.

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", "href": "/blog" }
    ],
    "primary": {
      "type": "button",
      "label": "Dashboard",
      "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.

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"
  },
  "styling": {
    "latex": true,
    "js": "/script.js"
  },
  "chat": {
    "starterQuestions": ["How do I get started?", "What endpoints are available?"]
  },
  "contextual": {
    "options": ["copy", "claude", "chatgpt", "mcp", "cursor"]
  },
  "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?