重新思考我们如何自定义用户界面

问题

🌐 The Problem

制作一个文档框架并不难，最困难的问题是如何从用户和开发者的角度让它对每个人都完美。毫无疑问，这对所有框架，甚至是库的作者来说都是一个两难境地——你无法编写开箱即用的通用代码，没有任何软件在保持通用性的同时可以直接使用。

🌐 Making a docs framework isn't challenging, the hardest problem is how I can make it perfect for everyone, from the perspective of users and developers. Undoubtedly, this is a dilemma for all frameworks, or even library authors — You cannot write generic code that works out-of-the-box, there's no piece of software that is straight usable while being generic.

例如，无头 UI 库如 Radix UI 给了我们通用 UI 组件的概念：裸露的 UI 基元，我们可以根据自己的美学进行定制。不过，你需要时间来调整它们，这些基元如果没有进一步的自定义是无法直接使用的。

🌐 For example, headless UI libraries like Radix UI gave us the concept of generic UI components: bare UI primitives that we can customise according to our aesthetics. However, you'll need time to tune them, these primitives are unusable without further customisations.

是的，现在是2025年，Shadcn UI 引领了 Web 开发的一场“革命”。它是无头 UI 和默认样式的绝佳结合，更进一步提高了开发效率！ 但我们的问题依然没有解决，当绝大多数新网站采用 Shadcn UI 时，它再次变得“无样式”，这可能显得荒谬。

🌐 Yep it's 2025, Shadcn UI had led a "revolution" on Web Development. It's a great combination of headless UI and styled defaults that takes an extra step away! But our problem remains unsolved, it might be preposterous that it becomes "unstyled" again when a vast majority of new sites adopted Shadcn UI.

就我个人而言，我对几乎相同、无处不在的扁平设计感到不知所措，这些显然是 Shadcn UI 的默认样式之一。这与 Shadcn UI 本身无关，而是与其他不真正关心美学和独特性的开发者有关。 最终，类似 Shadcn 的设计成为了默认样式，所以我们再次需要做一些额外的工作才能让它看起来更有风格。

🌐 Personally, I felt overwhelmed by nearly identical, ubiquitous flat designs that are obviously one of the default Shadcn UI styles. It has nothing to do with Shadcn UI, but the rest of developers who don't actually care about aesthetics and uniqueness. Eventually, Shadcn-like design became the default styles, so once again, we will need to do a bit more to make it look stylish.

我们应该怎么办？

🌐 What should we do?

作为一个以**“灵活”为起点**的文档框架，Fumadocs 必须可定制，并且能够根据开发者的偏好进行调整。 如果我们的目标是改善开发者体验（DX），我们就需要认真对待定制化。最重要的是，它应该鼓励有审美意识的开发者进行定制。

🌐 As a docs framework started from "being flexible", Fumadocs must be customisable, tuned to meet developers' preferences. We will need to take customisation seriously if DX is what we aim. And most importantly, it should encourage developers with a sense of beauty to customise.

解决方案

🌐 The Solution

通常，有两种类型的开发者：

🌐 Typically, there are two types of developers:

那些只想要直接可用文档的人

🌐 those who want docs that just work

Fumadocs 默认需要有明确的设计理念，以便可以立即使用，我们只需提供最简单的选项来更改细节。（例如颜色、覆盖组件）

🌐 Fumadocs need to be opinionated by default such that it is immediately usable, and we only have to offer simplest options to change details. (e.g. colors, overriding components).

大多数开发者不愿意仅仅为了修改一个小细节就安装几十个组件，这使得 Shadcn 的方法并不理想。

🌐 Most developers have no desire to install dozens of components just to change a tiny detail, which makes the Shadcn approach suboptimal.

那些需要根据自己偏好定制完美文档的人

🌐 those who need the perfect docs tailored to their preferences

Fumadocs 的核心，或者说我们追求的精神，是后者。我打造了 Fumadocs CLI，这是一个专门为 Fumadocs 定制的 Shadcn UI 版本，整个解决方案现在已经简化为一个命令：

🌐 The kernel of Fumadocs, or the spirit we're pursuing is the latter one. I crafted Fumadocs CLI, a version of Shadcn UI dedicated for Fumadocs, the whole solution is now simplified into a single command:

npx @fumadocs/cli customise

它分为两种类型：

🌐 It accounts for two types:

• 当提供的选项不足时，自定义默认样式。
• 从零开始设计自己的布局。

第一个是显而易见的，人们总是会有一些我们甚至都没有考虑到的荒谬需求。我们可以安装原始组件，这样它就与他们一直在使用的默认界面完全相同。

🌐 The first one is self-evident, people will always have absurd needs that we have not even considered. We can install the original components, so it's simply identical to the default UI which they've been using.

后者更简单，我们可以提供一个最基本的模板，他们可以从中开始自定义。

🌐 The latter one is simpler, we can offer the minimal template they can start customising from.

这种受喷射启发的方法带来了一些不错的优势：

🌐 This methodology, inspired by ejection, brings some nice advantages:

在升级 Fumadocs 时别弄坏任何东西

🌐 Don't break anything when you upgrade Fumadocs

Fumadocs 需要有自己的观点。因此，我们需要频繁迭代用户界面，这显然会破坏人们的临时自定义。Fumadocs CLI 的魅力在于，一旦你安装了布局，无论 Fumadocs UI 之后如何迭代，它都会保持不变。

🌐 Fumadocs need to be opinionated. Hence, we need to iterate the UI frequently which apparently will break people's hacky customisations. The charm of Fumadocs CLI is that once you've installed the layout, it stays the same forever regardless of future iterations on Fumadocs UI.

它为 Fumadocs 的 UI 提供了迭代的勇气，并让开发者在不畏升级依赖的情况下进行自定义。

🌐 It gives the courage for Fumadocs UI to iterate, and developers to customise unburnt by the fear of upgrading dependencies.

看起来很干净

🌐 Looks Clean

就像 Shadcn UI 和 Radix UI 一样，Fumadocs UI 也有一个核心包（fumadocs-core），大部分通用逻辑将由核心包抽象处理。

🌐 Just like Shadcn UI and Radix UI, Fumadocs UI has a core package (fumadocs-core), most generic logic will be abstracted by core.

下一步是什么？

🌐 What is Next?

Shadcn UI 的创新令人惊叹，但我相信 Fumadocs 还能解决更多问题。

🌐 The innovation of Shadcn UI is amazing, yet, I believe there's more problems Fumadocs can solve.

请参见 Flags SDK 和 BetterAuth，你一眼看不出来它们是否由 Fumadocs 提供支持。 我希望它能够继续作为一个以高度可定制性著称的“可破解”框架存在。

🌐 See Flags SDK and BetterAuth, you can't tell at the first glance if they're powered by Fumadocs. I hope it can continue to be a "breakable" framework known for how customisable it is.