Fumadocs UI 主题配置

开始使用

Fumadocs UI 目前只支持 Tailwind CSS v4，因此第一步是先接入下面这些必要的样式导入：

Tailwind CSS

@import 'tailwindcss';
@import 'fumadocs-ui/css/neutral.css';
@import 'fumadocs-ui/css/preset.css';

/* path of `fumadocs-ui` relative to the CSS file */
@source '../node_modules/fumadocs-ui/dist/**/*.js';

预设样式会带来什么变化

无论你使用 Tailwind CSS 插件还是预构建样式表，Fumadocs 都会调整项目中的默认边框、文字和背景颜色。

明暗主题

明暗模式切换由 next-themes 负责，这部分已经集成在 Root Provider 里。

完整说明可以查看 Root Provider。

RTL 支持

Fumadocs 同样支持从右到左的 RTL 布局。

如果要启用它，需要同时在 body 和 root provider 上设置 dir="rtl"，这样 Radix UI 组件才能保持一致。

import { RootProvider } from 'fumadocs-ui/provider';
import type { ReactNode } from 'react';

export default function RootLayout({ children }: { children: ReactNode }) {
  return (
    <html lang="en" suppressHydrationWarning>
      <body dir="rtl">
        <RootProvider dir="rtl">{children}</RootProvider>
      </body>
    </html>
  );
}

前缀机制

Fumadocs UI 自带一套颜色变量、动画和工具类。为了避免与 Shadcn UI 或你自己的样式变量冲突，默认会统一加上 fd- 前缀。

如果你希望使用不带前缀的别名，可以自己做一层映射：

Tailwind CSS

@theme {
  --color-primary: var(--color-fd-primary);
}

您可以将其与 CSS 媒体查询一起使用，实现响应式设计。

布局宽度

文档布局的最大宽度可以直接通过 CSS 变量调整。

:root {
  --fd-layout-width: 1400px;
}

Tailwind CSS 预设

预设层除了主题颜色之外，还额外提供了像 fd-steps 这样的工具类。

内置主题

Fumadocs 开箱即带来多套主题，你可以选择最适合当前产品风格的一种。

@import 'fumadocs-ui/css/<theme>.css';

/* Example */
@import 'fumadocs-ui/css/black.css';

Neutral

Black

Vitepress

Dusk

Catppuccin

Ocean

Purple

颜色系统

这套设计系统受到 Shadcn UI 的启发，而最直接的定制方式就是覆盖对应的 CSS 变量。

global.css

:root {
  --color-fd-background: hsl(0, 0%, 100%);
}

.dark {
  --color-fd-background: hsl(0, 0%, 0%);
}

排版

Fumadocs 内置了一套基于 Tailwind CSS Typography 改造而来的排版插件。

它会提供 prose 类以及一组可继续扩展的变体。

<div className="prose">
  <h1>Good Heading</h1>
</div>

该插件仅与 Fumadocs UI 的 MDX 组件一起工作，它可能与 @tailwindcss/typography 冲突。如果您需要使用 @tailwindcss/typography 而不是默认插件，请设置类名选项以避免冲突。

开始使用

Fumadocs UI 目前只支持 Tailwind CSS v4，因此第一步是先接入下面这些必要的样式导入：

Tailwind CSS

@import 'tailwindcss';
@import 'fumadocs-ui/css/neutral.css';
@import 'fumadocs-ui/css/preset.css';

/* path of `fumadocs-ui` relative to the CSS file */
@source '../node_modules/fumadocs-ui/dist/**/*.js';

预设样式会带来什么变化

无论你使用 Tailwind CSS 插件还是预构建样式表，Fumadocs 都会调整项目中的默认边框、文字和背景颜色。

明暗主题

明暗模式切换由 next-themes 负责，这部分已经集成在 Root Provider 里。

完整说明可以查看 Root Provider。

RTL 支持

Fumadocs 同样支持从右到左的 RTL 布局。

如果要启用它，需要同时在 body 和 root provider 上设置 dir="rtl"，这样 Radix UI 组件才能保持一致。

import { RootProvider } from 'fumadocs-ui/provider';
import type { ReactNode } from 'react';

export default function RootLayout({ children }: { children: ReactNode }) {
  return (
    <html lang="en" suppressHydrationWarning>
      <body dir="rtl">
        <RootProvider dir="rtl">{children}</RootProvider>
      </body>
    </html>
  );
}

前缀机制

Fumadocs UI 自带一套颜色变量、动画和工具类。为了避免与 Shadcn UI 或你自己的样式变量冲突，默认会统一加上 fd- 前缀。

如果你希望使用不带前缀的别名，可以自己做一层映射：

Tailwind CSS

@theme {
  --color-primary: var(--color-fd-primary);
}

您可以将其与 CSS 媒体查询一起使用，实现响应式设计。

布局宽度

文档布局的最大宽度可以直接通过 CSS 变量调整。

:root {
  --fd-layout-width: 1400px;
}

Tailwind CSS 预设

预设层除了主题颜色之外，还额外提供了像 fd-steps 这样的工具类。

内置主题

Fumadocs 开箱即带来多套主题，你可以选择最适合当前产品风格的一种。

@import 'fumadocs-ui/css/<theme>.css';

/* Example */
@import 'fumadocs-ui/css/black.css';

Neutral

Black

Vitepress

Dusk

Catppuccin

Ocean

Purple

颜色系统

这套设计系统受到 Shadcn UI 的启发，而最直接的定制方式就是覆盖对应的 CSS 变量。

global.css

:root {
  --color-fd-background: hsl(0, 0%, 100%);
}

.dark {
  --color-fd-background: hsl(0, 0%, 0%);
}

排版

Fumadocs 内置了一套基于 Tailwind CSS Typography 改造而来的排版插件。

它会提供 prose 类以及一组可继续扩展的变体。

<div className="prose">
  <h1>Good Heading</h1>
</div>

开始使用

预设样式会带来什么变化

明暗主题

RTL 支持

前缀机制

布局宽度

Tailwind CSS 预设

内置主题

颜色系统

排版

作者

分类

更多文章

Orelune Tarot Series: The Suit of Swords - Clarity, Conflict, and Mental Truth

Orelune 塔罗系列：正义——真相、平衡与承担

Orelune 上的 22 张大阿尔卡那解析

邮件列表

Fumadocs UI 主题配置

开始使用

预设样式会带来什么变化

明暗主题

RTL 支持

前缀机制

布局宽度

Tailwind CSS 预设

内置主题

颜色系统

排版

作者

分类

更多文章

Orelune Tarot Series: The Suit of Swords - Clarity, Conflict, and Mental Truth

Orelune 塔罗系列：正义——真相、平衡与承担

Orelune 上的 22 张大阿尔卡那解析

邮件列表