docs.json 参考

docs.json 文件是 Jamdesk 文档站点的中央配置文件。

必填字段

name

类型： string（必填）

文档站点的名称。显示在页眉和浏览器标签页中。

{ "name": "Acme API Docs" }

theme

类型： "jam" | "nebula" | "pulsar" | "halo"（必填）

colors

类型： object（必填）

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

品牌

favicon

类型： string 或 object

网站 favicon 文件的路径（推荐使用 SVG）。可以为两种模式提供同一张图片，也可以分别提供 light / dark 变体。

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

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

logo

类型： object

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

字体

fonts

类型： object（可选）

覆盖主题为正文和标题设置的默认字体。每个主题都提供经过调优的默认字体。只有在需要不同外观时才设置 fonts。

全局使用同一字体：

{
  "fonts": {
    "family": "Lora"
  }
}

分别设置标题和正文：

{
  "fonts": {
    "heading": { "family": "Space Grotesk" },
    "body": { "family": "Inter" }
  }
}

heading 和 body 接受相同的字段。有关选择字体的指导，请参阅主题 → 字体。

外观

appearance

类型： object（可选）

控制站点默认的深色模式行为。

{
  "appearance": {
    "default": "dark",
    "strict": true
  }
}

有关切换按钮行为，请参阅主题 → 深色模式。

页面元数据

metadata

类型： object（可选）

控制每个文档页面上显示的页面元数据。

{
  "metadata": {
    "timestamp": true
  }
}

日期会显示在已发布的站点和 jamdesk dev 中。它反映最近一次修改每个页面文件的提交，因此未编辑的页面会保留其原始日期。

横幅

banner

在每个页面顶部、页眉上方，以全宽和主题强调色显示站点范围的公告栏。可用于发布上线、迁移、维护窗口或所有访问者都应看到的消息。

{
  "banner": {
    "content": "🎉 Version 2.0 is live! Read the [changelog](/changelog).",
    "dismissible": true
  }
}

横幅会显示在已发布的站点和 jamdesk dev 中。它采用全局配置（整个站点使用一个横幅）；目前不支持按标签页或语言设置横幅。

OpenAPI

api.openapi

类型： string | string[]

列出要由 Jamdesk 验证并用于端点页面的 OpenAPI 3.x 规范文件。使用相对于 docs.json 的路径。

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

配置完成后，可以在页面的 frontmatter 中添加 openapi 字段来生成端点页面：

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

如果只列出一个规范，也可以使用简写格式：

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

有关实时端点页面，请参阅 OpenAPI 示例；有关文件放置位置，请参阅目录结构。

如果站点支持多语言，请在每个源规范旁放置一个 <spec>.<lang>.<ext> 文件（例如 openapi/api.fr.yaml），Jamdesk 会在对应语言的 URL 下提供该文件。请参阅翻译 OpenAPI 规范。

api.examples.languages

类型： string[] 默认值： ["curl", "python", "javascript"]

选择在 openapi: 页面自动生成的 API 代码示例中显示哪些编程语言。数组顺序决定标签页显示顺序，第一种语言默认处于选中状态。

支持的值： 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

类型： "required" | "all" 默认值： "all"

控制哪些参数会出现在自动生成的代码示例中。

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

api.examples.prefill

类型： boolean 默认值： false

为 true 时，API Playground 会使用 OpenAPI 规范中的 example 值预填参数字段。

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

api.playground.display

类型： "interactive" | "simple" | "none" 默认值： "interactive"

控制端点页面上的 API Playground。默认情况下，每个 openapi: 和 api: 页面都会显示“Try it”按钮。

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

有关使用详情和页面级覆盖设置，请参阅 API Playground。

api.mdx.auth.method

类型： "bearer" | "basic" | "key" | "cobo"

自动生成代码示例中使用的身份验证方法。设置后，示例会包含相应的身份验证标头。

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

api.mdx.auth.name

类型： string

基于密钥的身份验证所使用的自定义标头名称。仅当 api.mdx.auth.method 为 "key" 时使用。

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

导航

tabsPosition

类型： "top" | "left"

控制导航标签页的显示位置。

默认值取决于主题：

{ "tabsPosition": "left" }

anchors

类型： array

显示在所有页面侧边栏顶部的外部链接。

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

navigation (structure)

类型： object

文档的导航结构。有关详细文档，请参阅导航。

页面可以是字符串（根据文件名自动生成标题），也可以是带自定义标题的对象：

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

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

导航栏和页脚

navbar

类型： 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

类型： object

使用社交链接和自定义链接列配置页面页脚。

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

支持的社交平台： github、x、twitter、linkedin、discord、slack、youtube、instagram、facebook、reddit、telegram、bluesky、threads、medium、hacker-news、website

样式

styling.latex

类型： boolean

使用 KaTeX 启用 LaTeX 数学公式渲染。启用后，可以使用 $...$ 表示行内公式，使用 $$...$$ 表示块级公式。

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

有关使用详情，请参阅数学公式与 LaTeX。

styling.js

类型： string | string[]

在每个页面中包含自定义 JavaScript 文件。路径相对于文档目录，并且必须以 / 开头。

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

多个文件可以使用数组：

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

未设置此字段时，Jamdesk 会自动检测项目根目录中的 .js 文件。有关详情，请参阅自定义 JavaScript。

搜索

search

类型： object（可选）

自定义文档搜索栏。搜索开箱即用；只有在需要更改占位文本或在空状态中显示热门页面时，才需要设置此字段。

{
  "search": {
    "prompt": "Ask me anything…",
    "popularPages": [
      { "title": "Quick Start", "slug": "quickstart", "icon": "rocket" },
      { "title": "Authentication", "slug": "guides/authentication", "icon": "key" }
    ]
  }
}

热门页面

popularPages 中的每个条目接受以下字段：

icon 字段也接受完整的 { "name", "style", "library" } 对象。请参阅图标对象形式。省略 popularPages 时，Jamdesk 默认显示 Quick Start 和 Introduction。

聊天

chat

类型： object（可选）

配置内置的 AI 聊天助手。所有站点默认启用聊天；只有在需要自定义开场问题或禁用聊天时，才需要设置此字段。

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

有关聊天工作方式及访问者所见内容的详情，请参阅 AI 聊天。

AI 操作菜单

contextual

类型： object（可选）

配置显示在每个页面上的 AI 操作下拉菜单。默认启用所有选项；只有在需要自定义显示哪些选项或禁用菜单时，才需要设置此字段。

内置选项键： copy、view、chatgpt、claude、perplexity、gemini、mcp、cursor、vscode

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

可以将自定义选项与内置选项一起添加：

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

有关完整选项列表和自定义选项格式，请参阅 AI 操作菜单。

拼写检查

spellcheck

类型： object（可选）

配置 jamdesk spellcheck CLI 命令。只有在需要将项目专用词添加到忽略列表时，才需要设置此字段。

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

CLI 内置了 180 多个技术术语（API、GraphQL、Kubernetes、React 等），还会自动忽略 name 字段中的项目名称。只需添加项目专用词语。

有关使用详情和交互式修复模式，请参阅 CLI 概览：拼写检查。

图片

images.convertToWebp

类型： boolean（可选，默认值为 false）

在构建过程中为 PNG 和 JPG 资源启用自动 WebP 转换。转换后的文件通常比原文件小 60–80%，且不会出现可见的质量损失。MDX、自定义 CSS、自定义 JS 和 docs.json 中的引用都会自动重写，因此无需更改任何路径。

favicon、og:image 和 twitter:image 会保留原始格式。并非所有社交爬虫或电子邮件客户端都能可靠地渲染 WebP，而损坏的预览卡片比稍大的 JPG 更糟糕。

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

有关转换内容、缓存工作方式和构建进度指示器，请参阅自动图片转换。

访问控制

auth.password

类型： object（可选）

为站点启用共享密码保护。此处仅配置声明式设置。下一次构建完成后，仍需在仪表板中设置实际密码短语。

设置 auth.password.enabled: true 可锁定整个站点；也可以在 auth.password.private[] 下列出路径，仅保护指定页面。两种方式都会在下一次构建时触发相同的仪表板密码提示。

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

有关完整流程（包括仪表板操作流程，以及 frontmatter 中的 public: true / private: true 如何与这些数组交互），请参阅密码保护。

完整示例

{
  "$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"]
          }
        ]
      }
    ]
  }
}

下一步是什么？