站点级设置

用作标签栏标题的字符串。

为您的站点设置自定义 Logo。了解更多请参阅 logo 配置。

favicon 的相对路径。路径相对于设置该字段的 YAML 文件（例如 docs.yml）。

配置 primaryAccent 和 background 颜色。了解更多请参阅 colors 配置。

一个路径数组，配置后这些路径会永久重定向到其他路径。了解更多请参阅 redirects 配置。

作为操作号召（CTA）显示的链接的名称和 URL 数组。了解更多请参阅 navbar-links 配置。

设置在每个页面背后显示的自定义背景图片。了解更多请参阅 background-image 配置。

自定义文档站点中使用的字体。了解更多请参阅 typography 配置。

自定义文档站点的布局。了解更多请参阅 layout 配置。

自定义文档站点的设置。了解更多请参阅 settings 配置。

为您的文档站点创建一个落地页。了解更多请参阅 landing-page 配置。

设置 API Reference 中代码片段默认显示的语言。

可选项包括：typescript、python、java、go、ruby、csharp、php、swift、curl

为您的文档站点配置 SEO 元数据。了解更多请参阅 metadata 配置。

应用于本站点的全局主题 名称。发布时，CLI 会从 Fern 注册表中拉取指定主题，并将其品牌字段（Logo、颜色、字体、布局、CSS、JS 等）合并到本地的 docs.yml。使用此功能可在多个文档站点之间共享一致的视觉风格。

自定义 React 组件文件（TSX 或 JSX）的路径，用于替换 Fern 默认的页头。该组件必须有一个默认导出。了解更多请参阅自定义页头和页脚组件。

自定义 React 组件文件（TSX 或 JSX）的路径，用于替换 Fern 默认的页脚。该组件必须有一个默认导出。了解更多请参阅自定义页头和页脚组件。

配置一个或多个文档网站。

您的 Fern 文档发布的 URL。必须包含 docs.buildwithfern.com 后缀。

托管文档的自定义域名。了解更多请参阅设置自定义域名。

如果指定，会在每个页面底部添加”编辑此页面”链接，指向给定的公开 GitHub 仓库。您可以选择性地设置 launch 目标，以控制链接的跳转方式。了解更多请参阅 edit-this-page 配置。

指定本 instance 面向哪些受众（例如内部开发者、Beta 测试者、公开客户）。

您可以使用受众来控制哪些版本和产品出现在每个文档 instance 中，从而为不同用户群体创建独立的站点。当内容的 audience 标签与 instance 的 audience 匹配时，该内容会被包含在内；未设置 audience 标签的内容默认会被包含。了解更多请参阅为 products 和/或 versions 配置 instance audiences。

用于交互元素（如链接、按钮和高亮文本）的主要品牌色。请为浅色和深色模式分别配置颜色，以确保合适的对比度和可读性。

所有文档页面的主背景色。选择与文本对比良好的颜色，并与您的品牌颜色相协调。深色模式的颜色应能减轻眼部疲劳。

用于分隔线、元素边框和视觉分隔。请选择能清晰划分边界但不过于醒目的细腻颜色。

导航侧边栏的背景色。指定时，会在右侧添加 1 像素的边框。如果省略，侧边栏将使用透明背景且不带边框。

顶部导航头部的背景色。指定时，会在底部添加 1 像素的实线边框。如果省略，头部将使用带有微妙渐变边框的透明背景。

卡片、代码块及其他容器元素的背景色。应与主背景色略有差异，以营造视觉层次感同时保持可读性。

用户点击 Logo 时跳转到的 URL。通常是您公司的主页或应用。

深色模式 Logo 文件的路径，相对于设置该字段的 YAML 文件（例如 docs.yml）。建议使用 SVG 格式以获得最佳质量。示例：assets/images/logo-dark.svg

浅色模式 Logo 文件的路径，相对于设置该字段的 YAML 文件（例如 docs.yml）。建议使用 SVG 格式以获得最佳质量。示例：assets/images/logo-light.svg

显示在 Logo 图片右侧的文本。可用于在 Logo 旁添加诸如 “Docs” 或 “API” 之类的标签。

Logo 的自定义高度（像素）。如果默认高度不符合您的设计，可使用此项调整 Logo 大小。

The relative path you want to redirect from (e.g., /old-path). Must be a relative path, not an absolute URL. Must not include search parameters (e.g., ?key=value).

The path you want to route to. Can be an internal path (/new-path) or an external URL (https://example.com). External URLs must include the full address, including https.

By default, uses the 308 status code to instructs clients and search engines to cache the redirect forever. Set to false only if you need a temporary redirect using the 307 status code, which won’t be cached.

取值为 outlined、minimal、filled、github 或 dropdown 之一。该值控制按钮的样式。

点击按钮后跳转的 URL。示例：https://buildwithfern.com/contact

指向 GitHub 仓库的 URL。与 href 类似，但专用于 GitHub 仓库链接。当 type 设为 github 时使用此字段。示例：https://github.com/example-company/fern

按钮内显示的文本。

当为 true 时，按钮边角将完全圆角化。

按钮中使用的图标。该图标会出现在文本内容的左侧。

Icons can be in three formats:

• Font Awesome icons: Use icon names like fa-solid fa-rocket. Pro and Brand Icons from Font Awesome are supported.
• Custom image files: Use relative paths to image files (e.g., ./assets/icons/my-icon.svg or ../assets/icons/my-icon.png). Paths are relative to the YAML file where the icon is referenced (e.g., docs.yml). For example, if you set an icon in fern/products/my-product.yml, the path ./assets/icon.svg resolves to fern/products/assets/icon.svg. If you set it in fern/docs.yml, the same path resolves to fern/assets/icon.svg.
• Inline SVG: Provide an SVG string wrapped in quotes (e.g., "<svg>...</svg>").

按钮中使用的图标。该图标会出现在文本内容的右侧。

Icons can be in three formats:

• Font Awesome icons: Use icon names like fa-solid fa-rocket. Pro and Brand Icons from Font Awesome are supported.
• Custom image files: Use relative paths to image files (e.g., ./assets/icons/my-icon.svg or ../assets/icons/my-icon.png). Paths are relative to the YAML file where the icon is referenced (e.g., docs.yml). For example, if you set an icon in fern/products/my-product.yml, the path ./assets/icon.svg resolves to fern/products/assets/icon.svg. If you set it in fern/docs.yml, the same path resolves to fern/assets/icon.svg.
• Inline SVG: Provide an SVG string wrapped in quotes (e.g., "<svg>...</svg>").

默认情况下，filled 按钮的 rightIcon 会被设置为 arrow-right。

指定在哪里打开链接的 URL。对于典型的文档站点，链接可以在同一标签页（_self）或新标签页（_blank）中打开。对于嵌入在仪表板或 iframe 中的文档，链接可以在父框架（_parent）或最顶层框架（_top）中打开。

当 type 设为 dropdown 时，下拉菜单中显示的项。

链接显示的文本。

链接指向的 URL。

显示在文本左侧的 Font Awesome 图标。

显示在文本右侧的 Font Awesome 图标

当为 true 时，链接将具有完全圆角的边框。

指定在哪里打开链接的 URL。

您的 GitHub 仓库或组织的 URL。

您的 Slack 社区或工作区的 URL。

您的 X（前 Twitter）个人主页 URL。

您的 Twitter 个人主页 URL。如使用新的 X 品牌，请改用 footer-links.x。

您的 LinkedIn 公司主页或个人资料的 URL。

您的 YouTube 频道 URL。

您的 Instagram 主页 URL。

您的 Facebook 主页 URL。

您的 Discord 服务器邀请 URL。

您的 Hacker News 个人主页 URL。

您的 Medium 出版物或个人主页的 URL。

您的主网站或主页的 URL。

浅色模式背景图片的相对路径。路径相对于设置该字段的 YAML 文件（例如 docs.yml）。

深色模式背景图片的相对路径。路径相对于设置该字段的 YAML 文件（例如 docs.yml）。

用于所有正文内容（包括段落、列表和一般文本）的字体。为获得最佳性能，请使用 WOFF2 格式。

用于标题及其他突出文本元素的字体。如果您希望视觉风格统一，可以使用与正文字体相同的字体。支持为不同标题级别配置多种字重。

用于代码块和行内代码的字体。建议使用等宽字体以提高代码可读性。常用选择包括 JetBrains Mono、Fira Code 和 Source Code Pro。

字体名称。默认为自动生成的名称，用于在最终注入的 CSS 中引用您的自定义字体。

字体文件的路径，相对于设置该字段的 YAML 文件（例如 docs.yml）。当您只有一个字体文件时使用此项。对于多个字体文件（例如分别的 bold、italic 等），请改用 paths。

字体的字重。可以是数字（400、700），或可变字体的范围（400 700）。常用值：400（normal）、700（bold）。

字体样式，可选 “normal” 或 “italic”。如未指定，默认为 “normal”。

针对特定字重的字体文件列表。列表中的每个元素都包含 path、weight 和 style 属性。

设置头部的高度。默认为 4rem（64px）。可选值为 {number}rem 或 {number}px。

设置文档布局的最大宽度，包括侧边栏和内容。默认为 88rem（1408px）。可选值为 {number}rem、{number}px 或 full。

设置 Markdown 文章内容的最大宽度。默认为 44rem（704px）。可选值为 {number}rem 或 {number}px。

设置桌面模式下侧边栏的宽度。默认为 18rem（288px）。可选值为 {number}rem 或 {number}px。

设置搜索栏的位置。可选值为 header、sidebar 或 header-tabs（将搜索栏放在头部，但位于标签栏所在行）。

设置标签页的位置。可选值为 header 或 sidebar。

设置产品切换器和版本切换器的位置。可选值为 header 或 sidebar。

设置 Markdown 内容的对齐方式。可选值为 center 或 left。默认为 center。

设为 true 时不会渲染头部。Logo 将作为侧边栏的一部分渲染，并由 1 像素边框将侧边栏与内容分隔开。

设为 true 时不会渲染页面底部的导航链接（上一页/下一页）。可通过 frontmatter 在单个页面上覆盖此设置。

设为 true 时不会渲染反馈表单。可通过 frontmatter 在单个页面上覆盖此设置。

设为 true 时，在移动端和平板端视口（xl 断点以下）头部下方显示一个固定的目录栏。该栏会显示滚动进度指示器和当前所在标题，点击后可展开为完整的目录。

仅适用于使用 guide 和 overview 布局 的页面。当页面少于两个标题，或在 页面 frontmatter 中设置了 hide-toc: true 时，该目录栏会被隐藏。

设置导航侧边栏的视觉样式。default 显示带有分组标题和图标的完整侧边栏；minimal 显示更简洁、不含装饰性元素的简化侧边栏。

设置主内容区的视觉样式。default 使用平铺背景；canvas 在内容区域周围添加微妙的卡片式容器。

配置导航标签页。接受字符串（default 或 bubble）作为仅样式配置，或接受带有 style、alignment 和 placement 属性的对象进行完整控制。

当设置为字符串时，default 使用下划线样式的标签页，bubble 显示带圆角药丸状背景的标签页。

设置导航标签页的视觉样式。default 使用下划线样式；bubble 显示带圆角药丸状背景的标签页。

当 placement 为 header 时，设置标签页的水平对齐方式。left 表示左对齐；center 表示水平居中。当 placement 为 sidebar 时，对齐方式无效。

设置标签页的位置。header 表示在顶部导航头部显示标签页；sidebar 表示在左侧边栏显示。

当同时设置时，此项优先于 layout.tabs-placement。当 layout.disable-header 为 true 时，此设置将被忽略。

设置页面操作按钮的视觉样式。default 显示独立的图标按钮；toolbar 将这些操作合并为一个紧凑的水平工具栏。

设置页脚导航链接的视觉样式。default 显示带有标题和说明的完整上一页/下一页卡片；minimal 显示简单的文字链接。

设置 产品切换器 的视觉样式。default 显示下拉选择器；toggle 显示水平切换条。

搜索栏中显示的文本。

设为 true 时将禁用搜索栏。如果您想使用自定义搜索方案，请设为 true。

设为 true 时，API Explorer 会绕过代理直接将请求发送到您的 API。

设为 true 时，无论当前选择的主题如何，代码块都将以深色模式显示。

控制搜索结果是否默认限定为用户当前的产品和版本。

设为 false（默认）时，搜索会跨所有产品和版本返回结果。设为 true 时，搜索 UI 会自动筛选结果以匹配用户当前浏览的产品和版本。用户可以在搜索 UI 中移除这些筛选条件以扩大搜索范围。

控制 API Reference 中的 HTTP 代码片段 的显示。默认情况下所有语言的 HTTP 代码片段都会启用。

• 设为 false 可完全禁用 HTTP 代码片段
• 提供语言列表，仅为特定语言启用代码片段

1
# 仅为 Python 和 Ruby 启用
2
settings:
3
  http-snippets:
4
    - python
5
    - ruby

设为 true 时，用户导航到不存在的页面时将被重定向到首页。

默认情况下会显示 404 页面。

设为 true 时，API Reference 中的 TypeScript 代码片段将以 JavaScript 代码片段的形式显示。

设为 true 时，将禁用 analytics 配置 中配置的所有分析集成。包括 Google Analytics 4、Google Tag Manager、PostHog 以及您配置的任何其他分析服务商。

设置所有 文件夹导航 中页面和分组标题的默认派生方式。默认（filename）从文件名派生标题。设为 frontmatter 时改用每个文件 frontmatter 中的 title 字段（如未设置则回退到文件名）。每个文件夹可使用文件夹级 title-source 设置覆盖此全局默认值。

设为 true 时，会在构建时将 ${ENV_VAR} 表达式替换为对应环境变量的值。可用于在文档中注入 API 密钥、基础 URL 或版本号。

1
Connect to our API at ${API_BASE_URL}/v1
2
3
Your API key: ${API_KEY}

替换适用于 Markdown/MDX 文件和 API 规范（OpenAPI、Fern definitions）。JavaScript 文件已被排除，以避免与模板字符串冲突。

要输出字面意义的 ${VAR}，请将其转义为 \$\{VAR\}。

默认显示的页面操作。可选值：copy-page、view-as-markdown、ask-ai、chatgpt、claude、claude-code、cursor、vscode。

启用时会显示一个按钮，允许用户将整个页面内容复制到剪贴板，便于分享或参考。如需控制复制输出中包含哪些内容，请使用 <llms-ignore> 标签。

启用时会显示一个按钮，允许用户查看当前页面的原始 Markdown 源代码。用户也可以在页面 URL 后追加 .md 来查看 Markdown。如需控制 Markdown 输出中包含哪些内容，请使用 <llms-ignore> 标签。

启用时会显示一个”Ask AI”按钮，允许用户使用 AI 助手就页面内容进行提问。

控制”Open in ChatGPT”按钮，该按钮会将页面内容发送给 ChatGPT 以便进一步探索和问答。设为 false 可隐藏该按钮。

控制”Open in Claude”按钮，该按钮会将页面内容发送给 Claude 以便进一步探索和问答。设为 false 可隐藏该按钮。

控制”Connect to Claude Code”按钮，该按钮会将 claude mcp add 命令复制到剪贴板，便于用户在 Claude Code 中注册文档站点的 MCP 服务器。当启用 Ask Fern 时默认显示。设为 false 可隐藏该按钮。

控制”Connect to Cursor”按钮，该按钮通过 deeplink 在 Cursor 中安装文档站点的 MCP 服务器。当启用 Ask Fern 时默认显示。设为 false 可隐藏该按钮。

启用时会显示一个”Open in VS Code”按钮，允许用户在 Visual Studio Code 中打开页面内容进行编辑和开发。需启用 Ask Fern。

自定义页面操作配置数组。每个自定义操作会作为按钮显示在页面操作菜单中。

自定义操作按钮显示的标题。

可选的辅助说明文本，显示在操作菜单中标题下方。

点击该操作时跳转的 URL。支持以下占位符：

• {slug}：当前页面的 slug（例如 getting-started/quickstart）
• {domain}：当前域名（例如 docs.example.com）
• {url}：当前页面的完整 URL（例如 https://docs.example.com/getting-started/quickstart）

自定义操作显示的图标。

Icons can be in three formats:

• Font Awesome icons: Use icon names like fa-solid fa-rocket. Pro and Brand Icons from Font Awesome are supported.
• Custom image files: Use relative paths to image files (e.g., ./assets/icons/my-icon.svg or ../assets/icons/my-icon.png). Paths are relative to the YAML file where the icon is referenced (e.g., docs.yml). For example, if you set an icon in fern/products/my-product.yml, the path ./assets/icon.svg resolves to fern/products/assets/icon.svg. If you set it in fern/docs.yml, the same path resolves to fern/assets/icon.svg.
• Inline SVG: Provide an SVG string wrapped in quotes (e.g., "<svg>...</svg>").

设为 true 时，此自定义操作将成为在页面操作区域突出显示的默认操作。

如果您在某个自定义操作上设置了 default: true，请不要同时设置 page-actions.default，以免冲突。

拥有该文档仓库的 GitHub 组织。

包含您 fern 文件夹的 GitHub 仓库名称。

您希望 GitHub 编辑器提交 PR 到的仓库分支。默认为 main。

控制 “编辑此页面”按钮 的行为。设为 dashboard 时，点击按钮会打开一个界面，用户可以选择为该页面启动 Fern Editor 会话，或直接跳转到 GitHub 上的源文件（最适合内部站点）。默认为 github，即直接链接到 GitHub 上的文件（最适合面向公众的站点）。

落地页的名称。

目标落地页 Markdown 文件的相对路径。路径相对于设置该字段的 YAML 文件（例如 docs.yml）。

落地页的 slug。默认使用页面名称。

也可以在落地页 Markdown 文件的 frontmatter 中覆盖该 slug。

Open Graph 标签中显示的网站名称。

社交媒体预览中显示的标题。

社交媒体预览中显示的描述。

您文档的规范 URL。

社交媒体预览中显示的图片。推荐尺寸为 1200x630 像素。

Open Graph 图片的宽度（像素）。

Open Graph 图片的高度（像素）。

您内容的 locale（例如 “en_US”）。

您公司 Logo 的 URL。

Twitter Card 预览中显示的标题。

Twitter Card 预览中显示的描述。

您公司的 Twitter 用户名。

Twitter Card 预览中显示的图片。

您网站的 Twitter 用户名。

Twitter Card 类型。可选值：summary、summary_large_image、app 或 player。

设为 true 时，对未设置自定义 og:image 的页面启用动态 OG 图像生成。

动态生成的 OG 图像所使用的自定义背景图。可以是 URL 或相对文件路径。相对路径相对于设置该字段的 YAML 文件（例如 docs.yml）解析。

您文档站点的主机名。将用于设置元数据标签和站点地图等文档的规范 URL。

默认使用 instances 配置中定义的 URL。

您的 Google Analytics 4 measurement ID。必须以 “G-” 开头。

您的 Google Tag Manager container ID。必须以 “GTM-” 开头。

PostHog Analytics 集成的配置。

您的 PostHog 项目 API 密钥。默认使用 api-host “https://us.i.posthog.com”。

指向 Context7 验证文件的相对路径。设置后，Fern 会将该文件托管在您文档站点的 /context7.json 路径上。了解更多请参阅 Context7 集成。

Ask Fern 应索引和搜索的其他内容源。更多详情请参阅 其他内容源。

要索引的网站 URL。Ask Fern 将抓取并索引该 URL 的内容。

此数据源的可选显示名称。当 Ask Fern 引用该数据源的内容时，显示名称可帮助用户了解信息的来源。

默认情况下，Ask Fern 使用系统提示对 AI 搜索结果进行微调。可添加自定义 prompt 进行覆盖。

灵感和示例请参阅 Anthropic 的 提示工程指南。

当向 AI 代理提供页面的 Markdown 输出时，添加在每个页面前面的文本。该指令会注入到 frontmatter 元数据段之后、页面正文之前。面向人类的文档不受影响。未设置时使用默认指令，将代理指向您站点的 .md URL、llms.txt 和 llms-full.txt。设为空字符串可完全禁用该指令。

控制在 llms.txt 中优先使用哪个 frontmatter 字段作为页面的一行描述。默认为 description。如果首选字段在页面 frontmatter 中不存在，Fern 会回退到其他字段（description、subtitle、og:description、headline、excerpt）。

自定义 llms.txt 文件的路径，相对于 docs.yml。设置后，该文件会在站点根级别的 /llms.txt 端点提供，替代自动生成的版本。嵌套路径仍使用自动生成的输出。

自定义 llms-full.txt 文件的路径，相对于 docs.yml。设置后，该文件会在站点根级别的 /llms-full.txt 端点提供，替代自动生成的版本。嵌套路径仍使用自动生成的输出。

控制 API Reference 页面的 AI 生成示例。启用时，会生成贴近实际的示例值，替代 "string" 之类的占位值。x-fern-examples 或 OpenAPI example 属性中的手动示例始终优先。设为 false 可完全禁用 AI 示例。

用于指导 API Reference 中 AI 生成示例的内容和风格的说明。可用此项让示例符合您的品牌或领域风格。最多 500 个字符。

失效链接检测的严重级别。对失效的内部链接默认为 error，对格式错误的 URL 默认为 warn。替代已弃用的 --broken-links 和 --strict-broken-links CLI 标志。

OpenAPI 示例校验的严重级别。

非组件 OpenAPI 引用校验的严重级别。会标记指向 OpenAPI 规范 #/components 段以外位置的 $ref 值。

本地 OpenAPI 引用校验的严重级别。检查本地 $ref 值是否指向已存在的定义。

循环重定向校验的严重级别。检测重定向链路是否回到先前访问过的路径。

文档端点 URL 校验的严重级别。检查 docs.yml 中引用的端点 URL 是否格式正确。

缺失重定向检测的严重级别。将当前文档导航与之前发布的状态进行对比，标记被删除或移动到新 URL 但未在 docs.yml 中配置 redirect 的页面。需要进行身份验证（fern login 或 FERN_TOKEN 环境变量）。在首次发布、未登录或网络不可用时会跳过此检查。

控制动态 SDK 代码片段——允许用户修改参数并实时查看代码示例的更新。动态代码片段默认启用，并支持所有语言。请按照 SDK 代码片段配置说明 进行配置。设为 false 可改用静态 SDK 代码片段。