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 规范。

navigation openapi（生成的页面）

类型： object

在导航标签页上放置 openapi 对象并设置 generate: true 后，Jamdesk 会在构建时为该规范中的每个操作构建一个端点页面，并创建用于容纳这些页面的侧边栏分组。无需编写内容，也无需提交文件。

{
  "navigation": {
    "tabs": [
      {
        "tab": "API Reference",
        "openapi": { "source": "/openapi/api.yaml", "generate": true }
      }
    ]
  }
}

生成的页面位于该标签页自己的名称下，并经过 slug 化；slug 由方法和路径构成——上面的标签页会将 POST /tickets 放置在 /api-reference/post-tickets。操作按其第一个 tag 分组；没有标签的规范会回退到第一个有意义的路径片段，因此 /api/v1/auctions/{auctionId} 会归入 Auctions。如果规范包含操作 summary，标题取自该字段；否则使用方法和路径；针对单个资源的操作会使用单数标题（GET /users/{id} → “Get User”）。

已提交的 .mdx 文件始终优先于 slug 冲突，因此可以逐步采用生成机制：启用生成后，在准备好时逐个删除手写的端点页面。

如果之后重命名规范中的路径，生成的 slug 会随之移动。Jamdesk 会保留每个操作的 slug 历史记录，并在每次构建时将所有旧 URL 重定向到当前 URL，因此入站链接和书签不会因重命名失效。你自己的重定向和任何已存在的页面仍具有更高优先级。

当前限制。 生成机制仅对顶层 navigation.tabs 运行——不适用于分组、锚点，或嵌套在 languages 或 versions 下的标签页，并且只为默认语言生成页面。架构接受 directory 键，但它不会影响页面的放置位置。

api.mdx.server

类型： string

用于 api: frontmatter 页面代码示例的基础 URL（即 MDX 编写的页面，不是从规范中获取 server 的 openapi: 页面）。

{
  "api": {
    "mdx": {
      "server": "https://api.example.com"
    }
  }
}

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（结构）

类型： 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 Actions 下拉菜单。默认启用所有选项；只有需要自定义显示的选项或禁用该菜单时，才需要设置此字段。

内置选项键： 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 Actions 菜单。

拼写检查

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（可选）

选择启用网站的共享密码保护。该配置仅声明保护方式。你仍需在下一次构建运行后，通过 Dashboard 设置实际密码。

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

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

完整流程请参阅密码保护，其中包括 Dashboard 流程，以及 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"]
          }
        ]
      }
    ]
  }
}

下一步是什么？