配置

自定义 React 组件

以 Markdown 格式查看

您可以通过添加自定义 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 实例在同一页面上运行而降低性能
  • 创建用户必须下载的更大包体积

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