mintlify__docs/zh/organize/settings-structure.mdx

---
title: "站点结构"
description: "在 docs.json 中配置导航栏、页脚、横幅、重定向和其他结构设置。"
keywords: ["导航栏", "导航", "页脚", "横幅", "上下文", "重定向", "变量", "元数据", "docs.json"]
---

import IconsOptional from "/snippets/zh/icons-optional.mdx";

使用 `docs.json` 文件中的这些设置来控制站点的信息架构和用户体验。修改导航栏、页脚、横幅、导航行为、上下文菜单、重定向和全局内容变量。

## 设置

### `navigation` - <Badge color="red">必需</Badge>

**类型：** `object`

内容的导航结构。这是你使用组、标签页、下拉菜单、锚点等定义站点完整页面层次结构的地方。

有关构建导航结构的完整文档，请参阅[导航](/zh/organize/navigation)。

<ResponseField name="navigation.global" type="object">
  显示在所有页面和区域设置中的全局导航元素。

  <Expandable title="navigation.global">
    <ResponseField name="tabs" type="object 数组">
      用于组织主要部分的顶级导航标签页。请参阅[标签页](/zh/organize/navigation#tabs)。

      <Expandable title="tabs">
        <ResponseField name="tab" type="string" required>
          标签页的显示名称。最小长度：1。
        </ResponseField>
        <IconsOptional />
        <ResponseField name="hidden" type="boolean">
          是否默认隐藏此标签页。
        </ResponseField>
        <ResponseField name="href" type="string (uri)" required>
          标签页目标的 URL 或路径。
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="anchors" type="object 数组">
      在侧边栏中醒目显示的锚定链接。请参阅[锚点](/zh/organize/navigation#anchors)。

      <Expandable title="anchors">
        <ResponseField name="anchor" type="string" required>
          锚点的显示名称。最小长度：1。
        </ResponseField>
        <IconsOptional />
        <ResponseField name="color" type="object">
          锚点图标的自定义颜色。

          <Expandable title="color">
            <ResponseField name="light" type="string">
              浅色模式的锚点颜色。必须是以 `#` 开头的十六进制代码。
            </ResponseField>
            <ResponseField name="dark" type="string">
              深色模式的锚点颜色。必须是以 `#` 开头的十六进制代码。
            </ResponseField>
          </Expandable>
        </ResponseField>
        <ResponseField name="hidden" type="boolean">
          是否默认隐藏此锚点。
        </ResponseField>
        <ResponseField name="href" type="string (uri)" required>
          锚点目标的 URL 或路径。
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="dropdowns" type="object 数组">
      用于组织相关内容的下拉菜单。请参阅[下拉菜单](/zh/organize/navigation#dropdowns)。

      <Expandable title="dropdowns">
        <ResponseField name="dropdown" type="string" required>
          下拉菜单的显示名称。最小长度：1。
        </ResponseField>
        <IconsOptional />
        <ResponseField name="hidden" type="boolean">
          是否默认隐藏此下拉菜单。
        </ResponseField>
        <ResponseField name="href" type="string (uri)" required>
          下拉菜单目标的 URL 或路径。
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="languages" type="object 数组">
      本地化站点的语言切换器配置。请参阅[语言](/zh/organize/navigation#languages)。

      <Expandable title="languages">
        <ResponseField name="language" type='"ar" | "ca" | "cn" | "cs" | "de" | "en" | "es" | "fi" | "fr" | "fr-CA" | "he" | "hi" | "hu" | "id" | "it" | "ja" | "jp" | "ko" | "lv" | "nl" | "no" | "pl" | "pt" | "pt-BR" | "ro" | "ru" | "sv" | "tr" | "uk" | "uz" | "vi" | "zh" | "zh-Hans" | "zh-Hant"' required>
          [ISO 639-1](https://en.wikipedia.org/wiki/ISO_639-1) 格式的语言代码。
        </ResponseField>
        <ResponseField name="default" type="boolean">
          是否为默认语言。
        </ResponseField>
        <ResponseField name="hidden" type="boolean">
          是否默认隐藏此语言选项。
        </ResponseField>
        <ResponseField name="href" type="string (uri)" required>
          指向文档此语言版本的有效路径或外部链接。
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="versions" type="object 数组">
      多版本站点的版本切换器配置。请参阅[版本](/zh/organize/navigation#versions)。

      <Expandable title="versions">
        <ResponseField name="version" type="string" required>
          版本的显示名称。最小长度：1。
        </ResponseField>
        <ResponseField name="default" type="boolean">
          是否为默认版本。
        </ResponseField>
        <ResponseField name="hidden" type="boolean">
          是否默认隐藏此版本。
        </ResponseField>
        <ResponseField name="href" type="string (uri)" required>
          指向文档此版本的 URL 或路径。
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="products" type="object 数组">
      多产品站点的产品切换器。请参阅[产品](/zh/organize/navigation#products)。

      <Expandable title="products">
        <ResponseField name="product" type="string" required>
          产品的显示名称。
        </ResponseField>
        <ResponseField name="description" type="string">
          产品描述。
        </ResponseField>
        <IconsOptional />
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="navigation.languages" type="object 数组">
  [多语言](/zh/organize/navigation#languages)站点的语言切换器。除了导航结构外，每个条目还可以包含特定语言的 `banner`、`footer` 和 `navbar` 配置。

  <Expandable title="navigation.languages">
    <ResponseField name="language" type='"ar" | "ca" | "cn" | "cs" | "de" | "en" | "es" | "fi" | "fr" | "fr-CA" | "he" | "hi" | "hu" | "id" | "it" | "ja" | "jp" | "ko" | "lv" | "nl" | "no" | "pl" | "pt" | "pt-BR" | "ro" | "ru" | "sv" | "tr" | "uk" | "uz" | "vi" | "zh" | "zh-Hans" | "zh-Hant"' required>
      [ISO 639-1](https://en.wikipedia.org/wiki/ISO_639-1) 格式的语言代码。
    </ResponseField>
    <ResponseField name="default" type="boolean">
      是否为默认语言。
    </ResponseField>
    <ResponseField name="banner" type="object">
      特定语言的横幅配置。接受与顶级 [`banner`](#banner) 字段相同的选项。
    </ResponseField>
    <ResponseField name="footer" type="object">
      特定语言的页脚配置。接受与顶级 [`footer`](#footer) 字段相同的选项。
    </ResponseField>
    <ResponseField name="navbar" type="object">
      特定语言的导航栏配置。接受与顶级 [`navbar`](#navbar) 字段相同的选项。
    </ResponseField>
    <ResponseField name="hidden" type="boolean">
      是否默认隐藏此语言选项。
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="navigation.versions" type="object 数组">
  具有[多个版本](/zh/organize/navigation#versions)的站点的版本切换器。

  <Expandable title="navigation.versions">
    <ResponseField name="default" type="boolean">
      设置为 `true` 使其成为默认版本。如果省略，数组中的第一个版本为默认版本。
    </ResponseField>
    <ResponseField name="tag" type="string">
      在选择器中显示在版本旁边的徽章标签。用于突出显示版本，如 `"Latest"`、`"Recommended"` 或 `"Beta"`。
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="navigation.tabs" type="object 数组">
  顶级导航[标签页](/zh/organize/navigation#tabs)。
</ResponseField>

<ResponseField name="navigation.anchors" type="object 数组">
  侧边栏[锚点](/zh/organize/navigation#anchors)。
</ResponseField>

<ResponseField name="navigation.dropdowns" type="object 数组">
  用于分组相关内容的[下拉菜单](/zh/organize/navigation#dropdowns)。
</ResponseField>

<ResponseField name="navigation.products" type="object 数组">
  多[产品](/zh/organize/navigation#products)站点的产品切换器。
</ResponseField>

<ResponseField name="navigation.groups" type="object 数组">
  用于将内容组织成部分的[组](/zh/organize/navigation#groups)。
</ResponseField>

<ResponseField name="navigation.pages" type="string 或 object 数组">
  组成文档的各个[页面](/zh/organize/navigation#pages)。
</ResponseField>

<ResponseField name="navigation.directory" type='"none" | "accordion" | "card"'>
  导航分组中根页面的目录布局。设置后，具有 `root` 页面的分组会自动在页面内容下方显示其子页面列表。值通过导航树递归继承。后代可以覆盖。参见[目录列表](/zh/organize/navigation#directory-listings)。
</ResponseField>

---

### `navbar`

**类型：** `object`

显示在顶部导航栏中的链接和按钮。

<ResponseField name="navbar.links" type="object 数组">
  要在导航栏中显示的链接。

  <Expandable title="navbar.links">
    <ResponseField name="type" type='"github" | "discord"'>
      可选链接类型。省略时为标准文本链接。设置为 `github` 可链接到 GitHub 仓库并显示其 star 数。设置为 `discord` 可链接到 Discord 服务器并显示其在线用户数。
    </ResponseField>
    <ResponseField name="label" type="string">
      链接文本。未设置 `type` 时必需。对于 `github` 和 `discord` 可选。如果省略，Mintlify 会从 API 数据生成标签。
    </ResponseField>
    <ResponseField name="href" type="string (uri)" required>
      链接目标。必须是有效的外部 URL。对于 `github`，必须是 GitHub 仓库 URL。对于 `discord`，必须是 Discord 邀请 URL。
    </ResponseField>
    <IconsOptional />
  </Expandable>
</ResponseField>

<ResponseField name="navbar.primary" type="object">
  导航栏中的主要行动号召按钮。

  <Expandable title="navbar.primary">
    <ResponseField name="type" type='"button" | "github" | "discord"' required>
      按钮样式。选择 `button` 为标准按钮，`github` 为带 star 数的 GitHub 仓库链接，或 `discord` 为带在线用户数的 Discord 邀请。
    </ResponseField>
    <ResponseField name="label" type="string">
      按钮文本。当 `type` 为 `button` 时必需。对于 `github` 和 `discord` 可选。
    </ResponseField>
    <ResponseField name="href" type="string (uri)" required>
      按钮目标。必须是外部 URL。对于 `github`，必须是 GitHub 仓库 URL。对于 `discord`，必须是 Discord 邀请 URL。
    </ResponseField>
  </Expandable>
</ResponseField>

```json docs.json
"navbar": {
  "links": [
    { "type": "github", "href": "https://github.com/your-org/your-repo" },
    { "label": "社区", "href": "https://example.com/community" }
  ],
  "primary": {
    "type": "button",
    "label": "开始使用",
    "href": "https://example.com/signup"
  }
}
```

---

### `footer`

**类型：** `object`

页脚内容和社交媒体链接。

<ResponseField name="footer.socials" type="object">
  要在页脚中显示的社交媒体资料。每个键是平台名称，每个值是你的资料 URL。

  有效键：`x`、`website`、`facebook`、`youtube`、`discord`、`slack`、`github`、`linkedin`、`instagram`、`hacker-news`、`medium`、`telegram`、`twitter`、`x-twitter`、`earth-americas`、`bluesky`、`threads`、`reddit`、`podcast`

  ```json
  "socials": {
    "x": "https://x.com/yourhandle",
    "github": "https://github.com/your-org"
  }
  ```
</ResponseField>

<ResponseField name="footer.links" type="object 数组">
  显示在页脚中的链接列。最多 4 列。

  <Expandable title="footer.links">
    <ResponseField name="header" type="string">
      列标题。最小长度：1。
    </ResponseField>
    <ResponseField name="items" type="object 数组" required>
      要在列中显示的链接。

      <Expandable title="items">
        <ResponseField name="label" type="string" required>
          链接文本。最小长度：1。
        </ResponseField>
        <ResponseField name="href" type="string (uri)" required>
          链接目标 URL。
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

```json docs.json
"footer": {
  "socials": {
    "x": "https://x.com/yourhandle",
    "github": "https://github.com/your-org"
  },
  "links": [
    {
      "header": "公司",
      "items": [
        { "label": "博客", "href": "https://example.com/blog" },
        { "label": "招聘", "href": "https://example.com/careers" }
      ]
    }
  ]
}
```

---

### `banner`

**类型：** `object`

显示在每个页面顶部的全站横幅。

<ResponseField name="banner.content" type="string" required>
  横幅中显示的文本内容。支持基本 MDX 格式，包括链接、粗体和斜体文本。不支持自定义组件。

  ```json
  "content": "我们刚刚发布了新功能。[了解更多](https://example.com)"
  ```
</ResponseField>

<ResponseField name="banner.dismissible" type="boolean">
  是否显示关闭按钮以便用户关闭横幅。默认为 `false`。
</ResponseField>

```json docs.json
"banner": {
  "content": "我们刚刚发布了新功能。[了解更多](https://example.com)",
  "dismissible": true
}
```

---

### `interaction`

**类型：** `object`

控制导航元素的用户交互行为。

<ResponseField name="interaction.drilldown" type="boolean">
  控制选择导航组时的自动导航。设置为 `true` 可在组展开时自动导航到第一个页面。设置为 `false` 仅展开或折叠组而不导航。留空则使用主题的默认行为。
</ResponseField>

---

### `contextual`

**类型：** `object`

上下文菜单让用户快速访问 AI 工具和页面操作。它出现在页面标题或目录侧边栏中。

<Note>
  上下文菜单仅在预览和生产部署中可用。
</Note>

<ResponseField name="contextual.options" type="array" required>
  上下文菜单中可用的操作。数组中的第一个选项显示为默认操作。

  内置选项：
  - `"add-mcp"` — 将你的 MCP 服务器添加到用户的配置中
  - `"aistudio"` — 将当前页面发送到 Google AI Studio
  - `"assistant"` — 以当前页面为上下文打开 AI 助手
  - `"copy"` — 将当前页面复制为 Markdown 到剪贴板
  - `"chatgpt"` — 将当前页面发送到 ChatGPT
  - `"claude"` — 将当前页面发送到 Claude
  - `"cursor"` — 在 Cursor 中安装你托管的 MCP 服务器
  - `"devin"` — 将当前页面发送到 Devin
  - `"devin-mcp"` — 在 Devin 中安装你托管的 MCP 服务器
  - `"download-pdf"` — 将当前页面下载为 PDF
  - `"grok"` — 将当前页面发送到 Grok
  - `"mcp"` — 将你的 MCP 服务器 URL 复制到剪贴板
  - `"perplexity"` — 将当前页面发送到 Perplexity
  - `"view"` — 在新标签页中以 Markdown 查看当前页面
  - `"vscode"` — 在 VS Code 中安装你托管的 MCP 服务器
  - `"windsurf"` — 将当前页面发送到 Windsurf

  将自定义选项定义为对象：

  <Expandable title="自定义选项">
    <ResponseField name="title" type="string" required>
      自定义选项的显示标题。
    </ResponseField>
    <ResponseField name="description" type="string" required>
      自定义选项的描述文本。
    </ResponseField>
    <ResponseField name="icon" type="string">
      自定义选项的图标。支持图标库名称、URL、路径或 SVG 代码。
    </ResponseField>
    <ResponseField name="href" type="string 或 object" required>
      链接目标。可以是 URL 字符串或带有 `base` 和可选 `query` 参数的对象。

      可用占位符值：
      - `$page` — 当前页面内容
      - `$path` — 当前页面路径
      - `$mcp` — MCP 服务器 URL
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="contextual.display" type='"header" | "toc"'>
  显示上下文选项的位置。选择 `header` 在页面顶部上下文菜单中显示，或选择 `toc` 在目录侧边栏中显示。默认为 `header`。
</ResponseField>

```json docs.json
"contextual": {
  "options": ["copy", "view", "chatgpt", "claude"],
  "display": "header"
}
```

---

### `redirects`

**类型：** `object 数组`

用于已移动、重命名或删除页面的重定向。使用这些重定向在重新组织内容时保留链接。

<ResponseField name="redirects[].source" type="string" required>
  要重定向的源路径。示例：`/old-page`
</ResponseField>

<ResponseField name="redirects[].destination" type="string" required>
  要重定向到的目标路径。示例：`/new-page`
</ResponseField>

<ResponseField name="redirects[].permanent" type="boolean">
  如果为 `true`，发出永久重定向（308）。如果为 `false`，发出临时重定向（307）。默认为 `true`。
</ResponseField>

```json docs.json
"redirects": [
  {
    "source": "/old-page",
    "destination": "/new-page"
  },
  {
    "source": "/temp-redirect",
    "destination": "/destination",
    "permanent": false
  }
]
```

---

### `errors`

**类型：** `object`

自定义错误页面设置。

<ResponseField name="errors.404" type="object">
  404 "页面未找到" 错误页面的设置。

  <Expandable title="errors.404">
    <ResponseField name="redirect" type="boolean">
      当找不到页面时是否自动重定向到首页。默认为 `true`。
    </ResponseField>
    <ResponseField name="title" type="string">
      404 页面的自定义标题。
    </ResponseField>
    <ResponseField name="description" type="string">
      404 页面的自定义描述。支持 MDX 格式，包括链接、粗体和斜体文本以及自定义组件。
    </ResponseField>
  </Expandable>
</ResponseField>

```json docs.json
"errors": {
  "404": {
    "redirect": false,
    "title": "页面未找到",
    "description": "你要找的页面不存在。[返回首页](/)。"
  }
}
```

---

### `variables`

**类型：** `object`

在整个文档中使用的全局变量。Mintlify 在构建时使用 `{{variableName}}` 语法替换占位符为定义的值。

<ResponseField name="variables.[variableName]" type="string">
  键值对，其中键是变量名，值是替换文本。

  - 变量名可以包含字母数字字符和连字符。
  - 你必须定义内容中引用的所有变量，否则构建会失败。
  - Mintlify 会对值进行清理以防止 XSS 攻击。
</ResponseField>

```json docs.json
"variables": {
  "version": "2.0.0",
  "api-url": "https://api.example.com"
}
```

在内容中，使用双大括号引用变量：

```mdx
当前版本是 {{version}}。请求发送到 {{api-url}}。
```

---

### `metadata`

**类型：** `object`

全局应用的页面级元数据设置。

<ResponseField name="metadata.timestamp" type="boolean">
  在所有页面上启用最后修改日期。启用后，页面会显示内容最后修改的日期。默认为 `false`。

  你可以使用 `timestamp` frontmatter 字段为单个页面覆盖此设置。详情请参阅[页面](/zh/organize/pages#last-modified-timestamp)。
</ResponseField>

```json docs.json
"metadata": {
  "timestamp": true
}
```