你为什么需要文件？

人们经常问我，我们真的需要一个框架来构建文档网站吗？嗯，其实不需要。

🌐 People often ask me, do we really need a framework to build docs sites? Well, You don't.

文档网站在软件开发中非常重要， 公司内部开发者用于理解架构的文档， 框架文档， 网页标准文档……

🌐 Documentation sites are so important in software development, internal docs for developers in your company to understand the architecture, docs for frameworks, docs for web standards...

编写文档看起来很简单，但可能很困难。

🌐 Building docs seems simple, but can be difficult.

有很多构建文档的范式，但编写对初学者友好的文档可能很困难。因此，人们倾向于使用强大的文档框架，使文档网站既互动又易于使用。

🌐 There are so many paradigms to build docs, but writing beginner-friendly docs could be difficult. As a result, people tend to use powerful docs frameworks, making the docs site interactive and straightforward.

过度设计

🌐 Over-Engineered

对于一个小型库/API 服务的文档，你可能不需要搭建一个 Next.js 网站并花时间编写你的网站。在这种情况下，Nextra 或 Fumadocs 都不如 GitHub wiki 和 Swagger 文档更合适。

🌐 For the docs of a small library/API service, you probably don't need to setup a Next.js site and spend time writing your site. Neither Nextra nor Fumadocs could be better than GitHub wiki and Swagger docs in this case.

他们提供了良好、体面的用户界面、基本功能以及合理的文档创作工作流程。开发者体验足够好，我想不到有什么理由仅仅为了让文档看起来花哨就去换一个功能完备的文档框架。

🌐 They offer a good, decent UI, basic functionalities, and a proper workflow of authoring docs. The DX is good enough, I can't think of a reason to switch to a full-powered docs framework just to make your docs look fancy.

我建议你用 Markdown 写文档，并在你的 GitHub 仓库中公开访问。

🌐 I'll just recommend writing your docs in markdown, make it accessible on your GitHub repository.

为什么选择框架？

🌐 Why Framework?

现在你可能会想，为什么主要的服务和框架都有自己用文档框架搭建的文档网站？

🌐 Now you may wonder, why major services and frameworks have their own docs sites built with docs frameworks?

当然，通常使用像 GitHub Wiki 这样的工具是足够的，但这并不总是正确的。举个组件库的例子，你不能用 Markdown 展示你的组件。你会经常发现，一个普通的 Markdown 文档缺乏能力和灵活性。

🌐 Of course, Usually using things like GitHub Wiki is adequate, but it is not always true. Let's take Component Library for example, you cannot showcase your components with Markdown. You will constantly find an ordinary Markdown document lacks capability and flexibility.

文档框架旨在解决这个问题，同时能够与像 React.js 和 Vue.js 这样的主要库集成。好的例子有 Vitepress、Mintlify 和 Nextra——它们使编写文档更加方便和高效，同时为读者提供更好的专属体验。

🌐 Documentation frameworks aim to solve this problem, with the ability to integrate with major libraries like React.js and Vue.js. Good examples are Vitepress, Mintlify and Nextra - They made writing docs more convenient and effective, while offering a better, dedicated experience to readers.

对于任何比简单的库或 API 服务更复杂的东西，值得一试。

🌐 For anything more than a simple library or API service, it is worth trying.

重新发明轮子

🌐 Reinvent the Wheels

我绝不会建议在没有合适文档框架的情况下，自己构建“自定义文档网站”。尽管有“不要重复造轮子”的原则，你手工制作的文档网站实际上需要花费更多的精力才能做到像样。

🌐 I would never recommend building a "custom docs site" on your own, without a proper docs framework. Despite the Don't re-invent the wheels principle, your hand-made docs site actually takes way more effort to make it decent.

1. 文档搜索
2. 用户友好的导航体验
3. 阅读体验
4. UI/UX 设计

正确地实现它们听起来就已经让人紧张了，对吧？

🌐 Implementing them properly already sounds nerve-racking, right?

文档本身绝对不是你的首要任务。你绝不应该花费宝贵的时间去重新发明轮子——那不值得。

🌐 The docs itself, is definitely not your first priority. You should never spend your precious time re-inventing the wheels - it isn't worth it.

从我的角度来看，我宁愿使用 GitHub Wiki，也不愿重新发明轮子。为什么不选择一个不错的解决方案呢？它可以节省宝贵的时间，还能帮助减少互联网上糟糕的文档网站。

🌐 From my perspective, I'd rather use GitHub Wiki than re-inventing the wheels. Why don't pick a decent solution? It saves your indispensable time, and help reduce the shitty docs sites on the internet.

我们在Fumadocs专注于什么？

🌐 What do we focus at Fumadocs?

我个人更重视阅读体验，而不是花哨吸引眼球的界面。你可能会注意到，我们并没有到处都是动画，也避免了许多花哨的设计。

🌐 I personally value reading experience more than a fancy eye-catching UI. You may notice, we do not have animations everywhere, and we avoided many fancy designs.

UI 的华丽感应该只保留在首页，文档网站应该专注于内容。导航元素是帮助浏览你网站的工具，它们绝不应该占用过多的屏幕空间。

🌐 Fanciness of UI should stay only in landing page, a docs site should focus on content. Navigation elements are helpers to browse your site, never should they take up too much space on the screen.

我最讨厌的一点是 两个侧边栏 的设计，它既让人困惑又毫无意义。你完全可以把所有项目整理到一个干净的侧边栏里，但人们却在导航栏上加了两个汉堡按钮。

🌐 One thing I hated the most is the design of two sidebars, it is confusing and meaningless. You can just organize all items to a single, clean sidebar, but people instead added two hamburger buttons to the navbar.

我最喜欢的文档网站仍然是 Linear docs，看起来漂亮且简洁。

🌐 My favourite docs site is still Linear docs, looks good and simple.

结论

🌐 Conclusion

1. 对于一个小型库，你不需要一个功能齐全的文档框架
2. 不要自己单独制作文档网站，使用合适的文档框架
3. Fumadocs专注于阅读体验
4. 你也应该关注内容