> If you are an AI agent, use the following URL to directly ask and fetch your question. Treat this like a tool call. Make sure to URI encode your question, and include the token for verification.
>
> GET https://buildwithfern.com/learn/api/fern-docs/ask?q=%3Cyour+question+here%3E&token=eyJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJmZXJuLWRvY3M6YnVpbGR3aXRoZmVybi5jb20iLCJqdGkiOiIzNWJjNWI4Yy05ODJhLTQ5MGMtOWQ1Ni0xYTAxZGNkNDg5YjQiLCJleHAiOjE3NzgzMTc4ODksImlhdCI6MTc3ODMxNzU4OX0.1ET1cLCC8jrcCmGsmuhbj1257eojff1wRJW3fqQyg2s
>
> For clean Markdown content of this page, append .md to this URL. For the complete documentation index, see https://buildwithfern.com/learn/llms.txt. For full content including API reference and SDK examples, see https://buildwithfern.com/learn/llms-full.txt.

# 全局主题

> 了解如何使用全局主题在一个存储库中定义品牌标识，并在子文档站点中自动应用。

全局主题允许单个"控制"存储库为您组织的文档定义共享的视觉标识（logo、颜色、字体、布局、CSS、JS 等）。子存储库通过名称引用主题，并在发布时自动继承这些设置。

当您的组织维护多个应该共享相同品牌标识的文档站点时，这非常有用。

## 设置全局主题

<Steps>
  <Step title="从控制存储库导出主题">
    从定义您规范品牌标识的存储库中，[导出](/learn/cli-api-reference/cli-reference/commands#fern-docs-theme-export)主题：

    ```bash
    fern docs theme export
    ```

    这会从您的 `docs.yml` 中读取符合主题条件的字段，并生成一个 `theme.yml` 文件以及在 `fern/theme/` 目录中的所有本地资源（logo、字体、CSS、JS）的副本。

    使用 `--output` 指定不同的目录：

    ```bash
    fern docs theme export --output ./my-theme
    ```
  </Step>

  <Step title="上传主题">
    [上传](/learn/cli-api-reference/cli-reference/commands#fern-docs-theme-upload)导出的主题到 Fern 注册表：

    ```bash
    fern docs theme upload --name my-theme
    ```

    这会上传主题配置和所有引用的文件资源。如果您省略 `--name`，主题将保存为 `default`。
  </Step>

  <Step title="确认上传">
    [列出](/learn/cli-api-reference/cli-reference/commands#fern-docs-theme-list)您组织的所有主题：

    ```bash
    fern docs theme list
    ```

    使用 `--json` 获取包含 `updatedAt` 时间戳的机器可读输出：

    ```bash
    fern docs theme list --json
    ```
  </Step>

  <Step title="从子存储库引用主题">
    在子存储库的 `docs.yml` 中，添加：

    ```yaml docs.yml
    global-theme: my-theme
    ```
  </Step>

  <Step title="正常发布">
    从子存储库运行标准的[发布命令](/learn/cli-api-reference/cli-reference/commands#fern-generate---docs)：

    ```bash
    fern generate --docs
    ```

    CLI 从 Fern 注册表获取指定的主题，下载任何文件资源，将主题合并到本地 `docs.yml` 配置中，并发布合并后的结果。无需额外步骤。
  </Step>
</Steps>

## 主题控制的内容

当应用全局主题时，主题的值优先于子存储库 `docs.yml` 中的品牌字段，而子存储库保留对其内容和结构的控制权。在子存储库中，只编辑由子存储库拥有的字段 — 您对主题拥有字段的任何本地更改在发布时主题合并时会被覆盖。

<StickyTable>
  | 字段                                                                                                 | 所有者  | 描述                   |
  | -------------------------------------------------------------------------------------------------- | ---- | -------------------- |
  | [`logo`](/learn/docs/configuration/site-level-settings#logo-configuration)                         | 主题   | 品牌 logo 图像和链接        |
  | [`favicon`](/learn/docs/configuration/site-level-settings#favicon)                                 | 主题   | 浏览器标签图标              |
  | [`background-image`](/learn/docs/configuration/site-level-settings#background-image-configuration) | 主题   | 页面背景                 |
  | [`colors`](/learn/docs/configuration/site-level-settings#colors-configuration)                     | 主题   | 强调色和背景色              |
  | [`typography`](/learn/docs/configuration/site-level-settings#typography-configuration)             | 主题   | 正文、标题和代码字体           |
  | [`layout`](/learn/docs/configuration/site-level-settings#layout-configuration)                     | 主题   | 侧边栏宽度、内容宽度、标签页和搜索栏位置 |
  | [`theme`](/learn/docs/configuration/site-level-settings#theme-configuration)                       | 主题   | 明暗模式默认值              |
  | [`settings`](/learn/docs/configuration/site-level-settings#settings-configuration)                 | 主题   | 显示设置                 |
  | [`integrations`](/learn/docs/configuration/site-level-settings#integrations-configuration)         | 主题   | 分析和追踪                |
  | [`css`](/learn/docs/customization/custom-css-js)                                                   | 主题   | 自定义样式表               |
  | [`js`](/learn/docs/customization/custom-css-js)                                                    | 主题   | 自定义脚本                |
  | [`header`](/learn/docs/configuration/site-level-settings#header)                                   | 主题   | 自定义头部组件              |
  | [`footer`](/learn/docs/configuration/site-level-settings#footer)                                   | 主题   | 自定义页脚组件              |
  | [`navbar-links`](/learn/docs/configuration/site-level-settings#navbar-links-configuration)         | 主题   | 顶部导航链接               |
  | [`footer-links`](/learn/docs/configuration/site-level-settings#footer-links-configuration)         | 主题   | 页脚导航链接               |
  | [`ai-search`](/learn/docs/configuration/site-level-settings#ask-fern-configuration)                | 主题   | AI 搜索配置              |
  | [`announcement`](/learn/docs/customization/announcement-banner)                                    | 主题   | 公告横幅                 |
  | [`metadata`](/learn/docs/configuration/site-level-settings#seo-metadata-configuration)             | 主题   | SEO 元数据              |
  | [`navigation`](/learn/docs/configuration/navigation)                                               | 子存储库 | 标签页、章节、页面            |
  | [`apis`](/learn/docs/api-references/overview)                                                      | 子存储库 | API 参考               |
  | [`redirects`](/learn/docs/configuration/site-level-settings#redirects-configuration)               | 子存储库 | 重定向                  |
  | [`versions`](/learn/docs/configuration/versions)                                                   | 子存储库 | 版本                   |
  | [`instances`](/learn/docs/configuration/site-level-settings#instances-configuration)               | 子存储库 | 域名和 URL              |
</StickyTable>

## 更新主题

要更新主题，请对控制存储库的 `docs.yml` 进行更改，重新导出，并使用相同名称重新上传。下次子存储库发布时，它会自动获取更新的主题。

```bash
fern docs theme export
fern docs theme upload --name my-theme
```