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

网站图标文件的路径（推荐使用 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 中。它反映最近一次修改每个页面文件的提交，因此未编辑过的页面会保留原始日期。

本地化

localization

类型： object（可选）

控制访客如何进入文档的翻译版本。

{
  "localization": {
    "autoRedirect": true
  }
}

只有根路径会重定向。/guides/authentication 这样的深层链接始终提供它所指向的页面，因此您粘贴到工单里的链接对所有人打开的都是同一个页面。搜索引擎爬虫永远不会被重定向，由您的 hreflang 标签继续决定哪些内容被收录。

访客的语言会被记住一年。从语言选择器中选择语言后，从那时起该选择会覆盖自动匹配的结果。

完整行为请参阅多语言支持 → 自动语言路由。

横幅

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 编写的页面，不是从规范中获取服务器配置的 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 Chat。

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 Menu。

拼写检查

spellcheck

类型： object（可选）

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

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

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

有关用法详情和交互式修复模式，请参阅 CLI Overview: Spellcheck。

图片

images.convertToWebp

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

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

网站图标、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 如何与这些数组交互），请参阅密码保护。

auth.jwt

类型： object（可选）

使用你自己的登录系统保护整个网站。你的后端为每个已登录用户签署短期令牌，Jamdesk 将其交换为会话 Cookie。签名密钥在仪表板中生成，而不是在此文件中生成。不能同时启用 auth.jwt 和 auth.password；同时启用时，构建会因 config_error 失败。

{
  "auth": {
    "jwt": {
      "enabled": true,
      "loginUrl": "https://app.example.com/docs-login",
      "public": ["/changelog/**", "/status"]
    }
  }
}

在此基础上进行按页面访问控制，需要使用页面 frontmatter 中的 groups。有关令牌格式、重定向流程和分组工作方式，请参阅 JWT Authentication。

完整示例

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

下一步是什么？