完全自定义你的文档 | Fern Documentation

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

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

对于 MDX 内容中的服务端渲染可重用元素，请参阅自定义 React 组件。要替换 Fern 的默认页眉或页脚，请参阅自定义页眉和页脚。

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

自定义 CSS

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

创建 `styles.css`

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

添加 styles.css 文件

  fern/
  ├─ openapi/
  ├─ pages/
  ├─ images/
  ├─ styles.css
  ├─ docs.yml
  └─ fern.config.json

编辑 `docs.yml`

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

docs.yml

css: ./styles.css

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

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

docs.yml

css:
  - ./css/header-styles.css
  - ./css/footer-styles.css

要通过 Fern 的内置样式设计来自定义文档的背景、徽标、字体和布局，请查看全局配置。

内置 CSS 颜色变量

Fern 会从你的 docs.yml 颜色配置自动生成 CSS 变量，并将它们作为 CSS 自定义属性在样式表中提供。颜色会转换为 oklch 以确保一致的颜色管理，并为不支持的浏览器提供十六进制回退。这些变量会在明暗模式之间自动适配——明亮模式使用 .light 和 :root 选择器，而暗黑模式使用 .dark 选择器。

主色和灰阶

--accent-1 到 --accent-12 — 主色色阶（从 accent-primary 生成）
--accent-a1 到 --accent-a12 — 带透明度的主色色阶
--grayscale-1 到 --grayscale-12 — 灰阶色阶
--grayscale-a1 到 --grayscale-a12 — 带透明度的灰阶

命名颜色色阶

Fern 还会生成遵循 Radix UI 步骤范式的命名颜色色阶。这些匹配你的 accent-primary 色调，并包含像 --red-1 到 --red-12、--blue-1 到 --blue-12 以及其他颜色的色阶。

主题变量

--background — 页面背景颜色
--card-background — 卡片背景颜色
--border — 边框颜色
--sidebar-background — 侧边栏背景颜色
--header-background — 页眉背景颜色
--accent — 主要强调颜色

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

动态背景

使用 CSS 变量创建自动适应主题的背景。仅在需要特定主题样式时使用 .dark 选择器覆盖。

/* 使用 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%
  );
}

动态卡片

使用 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);
}

动态文本

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

/* 植物种类内容 */
.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);
}

动态图像

有多种方法可以让图像适应明暗模式。

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

HTML

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

CSS

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

切换背景图像：

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

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

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

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

CSS

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

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

常见用例

隐藏页面元素

你可以使用自定义 CSS 来隐藏不想显示的特定 Fern 文档组件。

styles.css

.fern-layout-footer-toolbar { # 隐藏 Fern 反馈小部件
  display: none !important;
}

你可以使用 CSS 类名来定位其他 Fern UI 组件。参阅 CSS 选择器参考获取所有可用选择器，或使用浏览器的开发者工具来检查元素。

添加自定义样式

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

styles.css

.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;
}

MDX 页面中的内联 CSS

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

page.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>

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

自定义 JavaScript

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

添加 custom.js 文件

  fern/
  ├─ openapi/
  ├─ pages/
  ├─ images/
  ├─ custom.js
  ├─ docs.yml
  └─ fern.config.json

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

docs.yml

js: ./custom.js

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

docs.yml

js:
  - path/to/js/file.js
  - path: path/to/another/js/file.js
    strategy: beforeInteractive
  - url: https://example.com/path/to/js/file.js

我们对本地源使用 path，对远程源使用 url。

策略

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

docs.yml

js:
  - path: path/to/another/js/file.js
    strategy: beforeInteractive

常见用例

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

自定义 CSS

创建 styles.css

编辑 docs.yml

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

内置 CSS 颜色变量

主色和灰阶

命名颜色色阶

主题变量

动态背景

动态卡片

动态文本

动态图像

常见用例

隐藏页面元素

添加自定义样式

MDX 页面中的内联 CSS

自定义 JavaScript

策略

常见用例

创建 `styles.css`

编辑 `docs.yml`