> 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.eyJpc3MiOiJmZXJuLWRvY3M6YnVpbGR3aXRoZmVybi5jb20iLCJqdGkiOiI4NmRjZTQ2ZC0zMDFlLTQ5YzAtOWI1YS01MzZhNzIyMjc5OWYiLCJleHAiOjE3NzgzMjEzMDAsImlhdCI6MTc3ODMyMTAwMH0.bCbKRdwMB5OrBfCRQZRNKrWVQBdg6Sm3k_BFtrnPiIg
>
> 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.

# 完全自定义你的文档

> 学习如何为你的 Fern 文档添加自定义 CSS、JavaScript 和 UI 组件。使用自定义类和脚本来设计你的文档样式。

本页面涵盖 CSS 和 JavaScript 自定义：

* **CSS** 用于样式设计、视觉变更和隐藏元素
* **JavaScript** 用于客户端行为、第三方集成和小部件

对于 MDX 内容中的服务端渲染可重用元素，请参阅 [自定义 React 组件](/learn/docs/customization/custom-react-components)。要替换 Fern 的默认页眉或页脚，请参阅 [自定义页眉和页脚](/learn/docs/customization/header-and-footer)。

你也可以[直接在 `docs.yml` 文件中自定义许多内容](/docs/configuration/site-level-settings)，包括颜色、排版、导航栏链接、布局、分析和元数据。在添加自定义代码之前，请先尝试这些内置选项。

## 自定义 CSS

你可以为文档添加自定义 CSS，以进一步自定义外观和感觉。定义的类名会应用到所有 MDX 文件中。请参阅 [CSS 选择器参考](/learn/docs/customization/css-selectors-reference) 获取可用的 `.fern-*` 选择器完整列表。

<Steps>
  ### 创建 `styles.css`

  添加一个 `styles.css` 文件并将其包含在你的 `fern/` 项目中：

  <CodeBlock title="添加 styles.css 文件">
    ```bash {5}
      fern/
      ├─ openapi/
      ├─ pages/
      ├─ images/
      ├─ styles.css
      ├─ docs.yml
      └─ fern.config.json
    ```
  </CodeBlock>

  ### 编辑 `docs.yml`

  在 `docs.yml` 中，指定 `styles.css` 文件的路径：

  <CodeBlock title="docs.yml">
    ```yaml
    css: ./styles.css
    ```
  </CodeBlock>

  ### 添加多个自定义 CSS 文件（可选）

  你可以指定任意数量的自定义 CSS 文件：

  <CodeBlock title="docs.yml">
    ```yaml
    css:
      - ./css/header-styles.css
      - ./css/footer-styles.css
    ```
  </CodeBlock>
</Steps>

<Note>
  要通过 Fern 的内置样式设计来自定义文档的背景、徽标、字体和布局，
  请查看 [全局配置](/learn/docs/configuration/site-level-settings)。
</Note>

### 内置 CSS 颜色变量

Fern 会从你的 [`docs.yml` 颜色配置](/learn/docs/configuration/site-level-settings#colors-configuration) 自动生成 CSS 变量，并将它们作为 CSS 自定义属性在样式表中提供。颜色会转换为 [oklch](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/oklch) 以确保一致的颜色管理，并为不支持的浏览器提供十六进制回退。这些变量会在明暗模式之间自动适配——明亮模式使用 `.light` 和 `:root` 选择器，而暗黑模式使用 `.dark` 选择器。

<AccordionGroup>
  <Accordion title="主色和灰阶">
    * `--accent-1` 到 `--accent-12` — 主色色阶（从 `accent-primary` 生成）
    * `--accent-a1` 到 `--accent-a12` — 带透明度的主色色阶
    * `--grayscale-1` 到 `--grayscale-12` — 灰阶色阶
    * `--grayscale-a1` 到 `--grayscale-a12` — 带透明度的灰阶
  </Accordion>

  <Accordion title="命名颜色色阶">
    Fern 还会生成遵循 [Radix UI 步骤范式](https://www.radix-ui.com/colors/docs/palette-composition/understanding-the-scale) 的命名颜色色阶。这些匹配你的 `accent-primary` 色调，并包含像 `--red-1` 到 `--red-12`、`--blue-1` 到 `--blue-12` 以及其他颜色的色阶。
  </Accordion>

  <Accordion title="主题变量">
    * `--background` — 页面背景颜色
    * `--card-background` — 卡片背景颜色
    * `--border` — 边框颜色
    * `--sidebar-background` — 侧边栏背景颜色
    * `--header-background` — 页眉背景颜色
    * `--accent` — 主要强调颜色
  </Accordion>
</AccordionGroup>

下方的手风琴显示了使用这些变量为背景、卡片、文本和图像设置主题的常见模式。

<AccordionGroup>
  <Accordion title="动态背景">
    使用 CSS 变量创建自动适应主题的背景。仅在需要特定主题样式时使用 `.dark` 选择器覆盖。

    ```css
    /* 使用 Fern 变量自动适配 */
    .fern-background-image {
      background-color: var(--background);
      background-image: linear-gradient(
        to bottom,
        color-mix(in srgb, var(--accent-9), var(--background) 85%) 0%,
        var(--background) 100%
      );
    }

    /* 为不同渐变方向显式的暗黑模式覆盖 */
    .dark .fern-background-image {
      background-image: linear-gradient(
        to bottom,
        var(--background) 0%,
        color-mix(in srgb, var(--accent-9), var(--background) 85%) 100%
      );
    }
    ```
  </Accordion>

  <Accordion title="动态卡片">
    使用 CSS 变量时，卡片会自动适应主题变化。仅对需要特定主题值的属性（如阴影）添加显式的暗黑模式覆盖。

    ```css
    /* 适应主题的植物目录卡片 */
    .fern-card.plant-card {
      background-color: var(--card-background);
      border-color: var(--border);
      color: var(--grayscale-12);
      box-shadow: 0 1px 2px var(--grayscale-a3);
    }

    .fern-card.plant-card.interactive:hover {
      box-shadow: 0 4px 12px var(--accent-a6);
    }

    /* 暗黑模式阴影调整 */
    .dark .fern-card.plant-card {
      box-shadow: 0 2px 6px var(--grayscale-a4);
    }
    ```
  </Accordion>

  <Accordion title="动态文本">
    使用 Fern 的灰阶和强调变量时，文本颜色会自动适应。使用 `--grayscale-12` 作为主要文本，`--grayscale-a11` 作为次要文本，`--accent-11` 作为链接。

    ```css
    /* 植物种类内容 */
    .plant-content {
      color: var(--grayscale-12);
    }

    .plant-content .description {
      color: var(--grayscale-a11);
    }

    .plant-content a {
      color: var(--accent-11);
      text-decoration-color: color-mix(in srgb, var(--accent-11), transparent 50%);
    }

    .plant-content a:hover {
      color: var(--accent-12);
    }
    ```
  </Accordion>

  <Accordion title="动态图像">
    有多种方法可以让图像适应明暗模式。

    **使用 currentColor 的 SVG 图标（推荐）：**

    ```html HTML
    <svg class="plant-icon" width="24" height="24" fill="currentColor">
      <!-- SVG paths -->
    </svg>
    ```

    ```css CSS
    .plant-icon {
      color: var(--grayscale-11);
    }

    .plant-icon.accent {
      color: var(--accent-11);
    }
    ```

    **切换背景图像：**

    ```css CSS
    .hero-plant {
      background-image: url('/assets/plants/hero-light.png');
      background-size: cover;
      background-position: center;
    }

    .dark .hero-plant {
      background-image: url('/assets/plants/hero-dark.png');
    }
    ```

    **使用带有 prefers-color-scheme 的 picture 元素：**

    ```html HTML
    <picture>
      <source srcset="/assets/plants/hero-dark.png" media="(prefers-color-scheme: dark)">
      <img src="/assets/plants/hero-light.png" alt="Plant species">
    </picture>
    ```

    <Warning>
      `prefers-color-scheme` 媒体查询遵循操作系统主题偏好，可能与你网站上的手动主题切换不匹配。为了与 Fern 的主题切换器完美对齐，请改用 `.dark` 选择器方法。
    </Warning>

    **使用 CSS 滤镜（最后手段）：**

    ```css CSS
    .logo-monochrome {
      filter: grayscale(1);
    }

    .dark .logo-monochrome {
      filter: invert(1) grayscale(1);
    }
    ```

    <Warning>
      避免在自定义 CSS 中硬编码十六进制颜色。始终使用 Fern 的 CSS 变量来维持适当的对比度和主题一致性。
    </Warning>
  </Accordion>
</AccordionGroup>

### 常见用例

<AccordionGroup>
  <Accordion title="隐藏页面元素">
    你可以使用自定义 CSS 来隐藏不想显示的特定 Fern 文档组件。

    <CodeBlock title="styles.css">
      ```css
      .fern-layout-footer-toolbar { # 隐藏 Fern 反馈小部件
        display: none !important;
      }
      ```
    </CodeBlock>

    你可以使用 CSS 类名来定位其他 Fern UI 组件。参阅 [CSS 选择器参考](/learn/docs/customization/css-selectors-reference) 获取所有可用选择器，或使用浏览器的开发者工具来检查元素。
  </Accordion>

  <Accordion title="添加自定义样式">
    你可以使用自定义 CSS 为文档中的表格、组件和其他元素创建品牌特定的样式。

    <CodeBlock title="styles.css">
      ```css maxLines=10

      .petstore-table {
          background-color: white;
          border: 1px solid #DEDEE1;
          border-radius: 4px;
      }

      .dark .petstore-table { 
          background-color: #1e1e1e;
          border: 1px solid #2e2e2e;
      }

      .petstore-table thead {
          position: sticky;
          top: 0;
      }

      .petstore-table thead tr {
          background-color: #edecee;
          border: 1px solid #DEDEE1;
          border-radius: 4px 4px 0px 0px;
      }

      .dark .petstore-table thead tr {
          background-color: #2e2e2e;
          border: 1px solid #2e2e2e;
      }

      .petstore-table th {
          padding: 6px;
      }

      .petstore-table tbody td {
          padding: 6px;
      }

      .petstore-table tbody tr:nth-child(odd) {
          border: 1px solid #DEDEE1;
      }
      .petstore-table tbody tr:nth-child(even) {
          border: 1px solid #DEDEE1;
          background-color: #f7f6f8;
      }

      .dark .petstore-table tbody tr:nth-child(odd) {
          border: 1px solid #2e2e2e;
      }

      .dark .petstore-table tbody tr:nth-child(even) {
          border: 1px solid #2e2e2e;
          background-color: #2e2e2e;
      }
      ```
    </CodeBlock>
  </Accordion>
</AccordionGroup>

### MDX 页面中的内联 CSS

你可以使用 `<style>` 标签直接在 MDX 页面中添加 CSS。这对于不需要全局应用的页面特定样式很有用。

<CodeBlocks>
  <CodeBlock title="page.mdx">
    ```mdx
    ---
    title: My page
    ---

    <style>
    {`
    .tropical-callout {
      background: linear-gradient(135deg, #2d5016 0%, #4a7c23 100%);
      border-radius: 8px;
      padding: 16px;
      color: white;
    }

    .dark .tropical-callout {
      background: linear-gradient(135deg, #1a3009 0%, #2d5016 100%);
    }
    `}
    </style>

    <div className="tropical-callout">
      龟背竹在明亮的间接光线下茁壮成长。
    </div>
    ```
  </CodeBlock>
</CodeBlocks>

CSS 必须用大括号和反引号（`{``}`）包装才能成为有效的 JSX。使用 `.dark` 选择器前缀来定义暗黑模式的样式。

## 自定义 JavaScript

通过注入全局自定义 JavaScript 来自定义文档网站的行为。添加一个 `custom.js` 文件并将其包含在你的 `fern/` 项目中：

<CodeBlock title="添加 custom.js 文件">
  ```bash {5}
    fern/
    ├─ openapi/
    ├─ pages/
    ├─ images/
    ├─ custom.js
    ├─ docs.yml
    └─ fern.config.json
  ```
</CodeBlock>

在 `docs.yml` 中，指定 `custom.js` 文件的路径：

<CodeBlock title="docs.yml">
  ```yaml
  js: ./custom.js
  ```
</CodeBlock>

你也可以指定本地存储和远程的多个自定义 JS 文件：

<CodeBlock title="docs.yml">
  ```yaml
  js:
    - path/to/js/file.js
    - path: path/to/another/js/file.js
      strategy: beforeInteractive
    - url: https://example.com/path/to/js/file.js
  ```
</CodeBlock>

<Note>
  我们对本地源使用 `path`，对远程源使用 `url`。
</Note>

### 策略

可选择为每个自定义 JavaScript 文件指定策略。从 `beforeInteractive`、`afterInteractive`（默认）和 `lazyOnload` 中选择。

<CodeBlock title="docs.yml">
  ```yaml
  js:
    - path: path/to/another/js/file.js
      strategy: beforeInteractive
  ```
</CodeBlock>

### 常见用例

* **第三方集成：** 对于 `docs.yml` 中不原生支持的工具，通过将嵌入代码片段粘贴到自定义 JS 文件中来添加分析、会话录制、支持小部件或标签管理器。参阅 [集成第三方工具](/learn/docs/integrations/overview#connect-other-integrations-via-custom-javascript) 获取支持的工具和示例。
* **自定义搜索：** 实现自定义搜索（还需要[你的 Algolia 凭据](/docs/customization/search)）
* **脚本和小部件：** 插入任何客户端脚本或可嵌入的小部件