Fumadocs 的早期错误

一个错误

🌐 A Mistake

Fumadocs 最初的错误是 Fumadocs CLI 推出得太晚，并且在文档中没有得到足够的提及。

🌐 The early mistake of Fumadocs was Fumadocs CLI being too late and not getting enough mentions on docs.

要进一步推进 CLI 方式，就像最近的 Shadcn CLI 支持一样，我们必须做出一些更改。如果早期使用者的自定义超出了我们抽象层能够缓解的范围，他们将会遇到问题。

🌐 To push the CLI approach further like the recent Shadcn CLI support, there's changes we have to made. Early adopters will face problems if their customisations went beyond what our abstraction can mitigate.

例如： 一个小的 CSS 改动仍然可能破坏不规范的 CSS 自定义，我们只能确保通过 CSS 选择器范围限定的或公开选项的向后兼容性：

#nd-sidebar {
  /* this will work forever */
  background-color: red;
}

为了让命令行接口（CLI）运行得更好，我们需要布局组件完全独立，以便实现模块化。理想状态是：

🌐 For CLI to work better, we need layout components to be entirely independent for modularization. A ideal state is that:

• 普通用户可以使用暴露的选项，享受上游的界面迭代。
• 高级自定义可以使用 Fumadocs CLI，无需上游更改。

与这篇关于界面自定义的帖子中描述的解决方案相同。

🌐 Same as the solution described in this post about UI Customisation.

一个好例子

🌐 A Good Example

对于像 nuqs 那样的轻量级自定义，提交一个将旧版本迁移的 PR #1056 可以减少用户端的代码，而且迁移很简单。

🌐 For lighter customisations like nuqs did, a PR to migrate from old versions #1056 can reduce code on user land and migration is simple.

问题

🌐 The Problems

当你的漏洞更多时，迁移会更困难，再加上代码库的技术债务。

🌐 When your hacks is heavier, migration is much harder combined with the tech debt of your codebase.

我观察到的一些问题：

🌐 Some problems I observed:

页面树 API 被忽视

🌐 Page Tree API being Neglected

页面树实际上是 Fumadocs 的一个关键概念，统一了所有文档的导航和链接。

🌐 Page tree is actually a crucial idea of Fumadocs, unifying all navigation & linking of docs.

即使在早期，它已经是一个功能强大的 API，支持诸如根文件夹（自 v12 起）等功能：

🌐 Even in the early days, it's already a robust API supporting features like Root Folder (since v12):

有些项目没有依赖我们的基于文件的路由或页面树 API，这导致在侧边栏和 loader() 上出现了很多临时解决方法。

🌐 Some projects didn't rely on our file-based routing nor page tree API, which resulted in a lot of hacks around sidebar & loader().

它的想法很简单：

🌐 Its idea is simple:

files -> Fumadocs -> page tree

正确使用它已经可以减少大量工作，我们有页面树规范用于硬编码页面树。

🌐 Using it properly can already reduce a massive amount of work, we have a specs for Page Tree for hardcoded page trees.

CSS 变量被忽视

🌐 CSS Variables being Neglected

Fumadocs 从一开始就使用 CSS 变量来定义所有颜色，其命名方式与 Shadcn UI 完全相同，这使得自定义变得容易。

🌐 Fumadocs is using CSS variables for all colors since the beginning, the naming is identical to Shadcn UI which makes customisation easy.

但我注意到有些人覆盖的是 Tailwind CSS 的 类 而不是 颜色，比如：

🌐 But I noticed some are overriding the Tailwind CSS classes rather than colors, like:

#nd-sidebar .color-fd-background\/80 {
  color: red;
}

事实上，我们一直支持一种更简单的方式：

🌐 In fact we always support a simpler way:

#nd-sidebar {
  --color-fd-foreground: red;
}

现在我们还有一个 Shadcn UI 预设，可以在主应用中重用你的颜色。

🌐 Now we also have a Shadcn UI preset to reuse your colors from main app.

早期思考

🌐 Early Reflections

我认为命令行接口方法是正确的，它将是高级定制的主要方式。

🌐 I think the CLI approach is correct, it'll be the primary way for advanced customisation.

我的未来计划：

🌐 My future plans:

• 继续改进 Fumadocs CLI： 添加安装时优化，根据你的选项删除未使用的文件（例如，使用现有的侧边栏组件而不是安装新的组件）。
• 更好的版本控制策略： 降低抽象以减轻上游更改的影响，而是直接对组件进行版本控制（例如，创建一个新的 fumadocs-ui/layouts/v2/page，而不是进行重大 UI 更改）。
• 添加 Fumadocs 原生云功能： 提供更多官方集成，例如为 Fumadocs 设计的监控/分析功能。

我最大的目标是建立自己的开发团队或创业公司，我意识到我的时间太有限，无法实现我想象中的优秀软件。总有一些粗糙的地方我没时间去打磨，而且事情太多——即使 AI 已经处理了基础工作。

🌐 My biggest goal is to build my own dev team or startup, I realized my time is too limited to build the excellent software in my imaginary. There's rough edges that I never found time to polish, and too many things to do - even if AI has handled the basic work.

这就是我想说的 :)

🌐 That's all I want to say :)

欢迎提出问题（通过私信或GitHub），我很乐意在有时间的时候改进不足之处。

🌐 Welcome for questions (via DM/GitHub), I'm happy to improve rough edges whenever I have time.