查看全新的 Node.js API 文档预览
Guilherme Araújo
我们一直在重构 Node.js 生成和呈现其 API 文档的方式,预览版现已在 beta.docs.nodejs.org 上线。在它成为默认版本之前,我们希望尽可能多的人在实际工作中使用它,并告诉我们你的想法。
对读者而言有哪些不同
内容本身并未改变:每个页面都由 nodejs/node 仓库中相同的 Markdown 文件生成,这些文件也支撑着当前文档。你目前依赖的功能也都一并迁移了过来:浅色和深色主题、ESM/CJS 切换和代码片段复制按钮、稳定性徽章、版本历史,以及每个页面的 Markdown 版本。
不过,这次重新设计不仅仅涉及视觉层面:导航、布局和可读性都经过了重做,使查找和理解 API 更加省力。除此之外,测试版还加入了当前文档从未有过的功能:
- 搜索:API 文档首次内置搜索功能。每个页面都有一个搜索框,并配有键盘快捷键,让你无需绕道搜索引擎即可跳转到 API 的任意位置。
- 全项目统一设计:API 文档现在与 nodejs.org 网站共享同一套设计系统,包含列出每个模块的常驻侧边栏、始终可见的每页目录,以及适用于小屏幕的布局。
- llms.txt:我们已经发布了 llms.txt,为 AI 工具提供一个清晰、结构化的 API 参考入口。
这还不是全部:测试版还附带了阅读时长和公告横幅等功能。
我们也关心每位用户的需求,并会留意那些容易被忽视的需求。即使禁用 JavaScript 并处于离线状态,每个页面仍可使用。
底层实现
重新设计后的文档使用 doc-kit 构建;这是由 Node.js Project 开发的独立工具,用于替代之前的旧版文档生成器。
有关 doc-kit 及其在其他项目中的功能,请参阅 其仓库。这里也将成为跟踪错误报告、功能请求和其他任务的地方。
我们需要你的反馈
尽管我们很自豪地表示,重新设计后的文档正在进入开发的最后阶段,反馈仍然是此次迁移中至关重要的一部分,我们也希望听听你对此过程的想法。如果你发现任何问题,无论大小,请在 nodejs/doc-kit 仓库中提交 issue。
致谢
如果没有 Node.js Web Team,这一切都不会存在;该团队成员设计、构建并审查了本文中描述的所有内容。也感谢 Node.js 社区,以及在整个过程中通过审查、测试并提出建议提供过帮助的协作者。感谢大家让这一切成为可能。