Fumadocs 的早期错误

一个错误

Fumadocs 的早期错误是 Fumadocs CLI 发布太晚，并且在文档中没有得到足够的提及。

要像最近的 Shadcn CLI 支持那样进一步推动 CLI 方法，我们必须进行一些更改。 如果早期采用者的自定义超出了我们抽象能够缓解的范围，他们将面临问题。

例如： 一个小的 CSS 更改仍然可能破坏 hacky 的 CSS 自定义，我们只能确保通过 CSS 选择器范围或暴露选项的向后兼容性：

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

为了让 CLI 更好地工作，我们需要布局组件完全独立以实现模块化。理想状态是：

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

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

一个好的例子

对于像 nuqs 那样的较轻自定义，从旧版本迁移的 PR #1056 可以减少用户端的代码，并且迁移很简单。

问题

当你的 hack 更重时，结合代码库的技术债，迁移会变得更加困难。

我观察到的一些问题：

页面树 API 被忽视

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

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

一些项目没有依赖我们的基于文件的路由或页面树 API，这导致了大量围绕侧边栏和 loader() 的 hack。

它的想法很简单：

files -> Fumadocs -> page tree

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

CSS 变量被忽视

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

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

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

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

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

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

早期反思

我认为 CLI 方法是正确的，它将成为高级自定义的主要方式。

我的未来计划：

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

我的最大目标是建立自己的开发团队或初创公司，我意识到我的时间太有限，无法构建我想象中的优秀软件。 有一些粗糙的边缘我从未找到时间来打磨，还有太多事情要做——即使 AI 处理了基本工作。

这就是我想说的全部 :)

欢迎提问（通过 DM/GitHub），我很乐意在有时间时改进粗糙的边缘。