For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
预约演示登录免费开始
  • 入门
    • 概览
    • 工作原理
    • 快速开始
    • 项目结构
    • Customer showcase
    • 变更日志
  • 配置
    • 概览
    • 站点级设置
    • 页面级设置
  • 编写内容
    • Markdown 基础
    • Markdown 中的富媒体
    • Fern 编辑器
    • 可复用代码片段
  • AI 功能
    • 概览
    • Fern Writer
    • AI 生成的示例
    • Markdown 访问
      • 概览
      • Agent 指令
      • 智能体指令
      • 分析与集成
    • MCP 服务器
    • API 目录发现
      • 概览
      • 嵌入模式
      • Hiding content
      • Search
      • 收集用户反馈和建议
      • 完全自定义文档
      • CSS 选择器参考
      • 自定义 React 组件
      • 页眉和页脚
      • 全局主题
  • Public API
    • GETJWT from Fern API key
    • GETAlgolia search credentials
    • GETCurrent user information
  • Fern Writer API
    • GETGet Fern Writer Install Link
Checking status...
SOC2Soc 2 Type II
© 2026 Fern • Birch Solutions, Inc., a Postman company

Documentation

SDKsDocsAsk FernCLI Reference

API Definitions

OpenAPIAsyncAPIOpenRPCgRPC

Resources

BlogSupportPricing

Company

Brand KitPrivacy PolicyTerms of Service
LogoLogo
预约演示登录免费开始
在本页
  • MDX 中的自定义组件
  • 为什么不直接使用自定义 CSS 和 JS?
配置

自定义 React 组件

||以 Markdown 格式查看|
此页面是否有帮助?
在仪表板中编辑
上一个

CSS 选择器参考

下一个

页眉和页脚

您可以通过添加自定义 React 组件来扩展 Fern 的内置组件库。这允许您创建符合文档需求的独特交互式元素。组件采用服务端渲染,具有更好的 SEO 和性能表现,且不会出现布局偏移。

定义常量

不要使用 React 组件来定义常量。请考虑使用可重用片段。

MDX 中的自定义组件

1

创建 React 组件

让我们首先创建一个 components 文件夹,您可以在其中定义 React 组件。请注意,React 组件可以在 .ts、.tsx、.js 或 .mdx 文件中定义。

components/CustomCard.tsx
1 export const CustomCard = ({ title, text, link, sparkle = false }) => {
2 return (
3 <a href={link} className="block p-6 rounded-lg border border-gray-200 hover:shadow-lg transition-shadow">
4 <h2 className="text-xl font-semibold mb-2">
5 {title} {sparkle && "✨"}
6 </h2>
7 <p className="text-gray-600">{text}</p>
8 </a>
9 );
10 };
2

在文档中使用组件

编写好组件后,您可以使用相对路径或 @/ 前缀(从 fern 文件夹根目录开始的绝对路径)在 Markdown 指南中导入它:

guide.mdx
1// 从 fern 文件夹根目录开始的绝对路径
2import { CustomCard } from "../../../../components/CustomCard"
3
4// 或使用相对路径
5import { CustomCard } from "../components/CustomCard"
6
7<CustomCard
8 title="MyTitle"
9 text="Hello"
10 href="https://github.com/fern-api/fern/tree/main/generators/python"
11/>

@/ 前缀解析为 fern 文件夹的根目录,因此 @/components/CustomCard 指向 fern/components/CustomCard。这对于嵌套的 MDX 文件很有用,因为相对路径会很麻烦(例如 ../../../components/CustomCard)。两种导入方式在发布时都会自动转换为相对路径。

3

在 docs.yml 中指定组件目录

在 docs.yml 中添加您的组件目录,这样 Fern CLI 就可以扫描您的组件目录并将它们上传到服务器。

docs.yml
1experimental:
2 mdx-components:
3 - ./components

为什么不直接使用自定义 CSS 和 JS?

虽然您可以将 React 组件打包为自定义 JavaScript,但使用 Fern 内置的 React 组件支持提供了几个关键优势:

无布局偏移或闪烁

通过自定义 JavaScript 添加 React 组件时,您无法控制组件相对于页面其他内容的渲染时机。这通常会导致故障行为,组件在主内容加载后异步加载时会出现闪烁或跳跃。

更快的页面加载

自定义 JavaScript 包通常包含自己的 React 库副本,这会:

  • 通过重复已包含的 React 代码增加页面加载时间
  • 由于多个 React 实例在同一页面上运行而降低性能
  • 创建用户必须下载的更大包体积
改进的 SEO

自定义 React 组件采用服务端渲染,完全可被搜索引擎索引,而通过自定义 JavaScript 添加的组件不采用服务端渲染,无法被索引。