Introduction

免责声明

自从我们发布 Docusaurus 2 的第一个 alpha 版本 以来已经一年了,此后一切一直稳定。 Facebook 的许多新开源项目的网站现在都在使用 Docusaurus 2。在这一点上,我们强烈建议您在新网站上使用 Docusaurus 2,而不是 Docusaurus 1。如有反馈和问题,请在 Discord 上如我们交流 😉

如果满足以下条件,则应使用 Docusaurus 2:

  • ✅ 你希望为 Docusaurus 2 做贡献
  • ✅ 您想使用客户端路由和预渲染功能构建一个现代化的网站
  • ✅ 您想提供反馈以确保 Docusaurus 2 满足您的需求
  • ✅ 作为 Docusaurus 用户,您对下一步的发展感到好奇
  • ✅ 您希望将来减轻将来迁移的痛苦
  • ✅ 您不需要支持 IE11

如果有以下情况,请使用 Docusaurus 1:

  • ❌ 需要一个完全可用于生产级的解决方案 (请转到 Docusaurus 1
  • ❌ 您需要 v1 版本中提供的翻译功能
  • ❌ 您不希望使用潜在的重大更改和/或无法正常使用的功能,因为我们会在 Alpha 版本期间对其进行(较大)改进
  • ❌ 您需要支持 IE11

更好的 Docusaurus 来了

Docusaurus

Docusaurus 1 曾是一个纯粹的文档站点生成器。在 Docusaurus 2 中,我们从头开始对其进行了重新构建,以实现更高的可定制性,但保留了 Docusaurus 1 中最好的部分,即易于上手、文档版本化和 i18n(即将推出)。

除此之外,Docusaurus 2 是一款性能卓越的静态网站生成器,可用于快速创建常见的内容驱动型网站(例如文档、博客、产品落地页和营销页等)。

尽管我们主要关注的是帮助您正确地构建文档网站,但可以使用 Docusaurus 2 来构建任何类型的网站,因为它只是一个 React 应用程序。 Docusaurus 现在可以用于构建任何类型的网站,而不仅仅是文档网站。

特性

在构建 Docusaurus 时,我们非常重视您在构建站点以及与合作者和贡献者进行维护方面的经验。

  • ⚛️ 构建在 💚 和 React 之上
    • 可利用 React 进行扩展和定制
    • 利用 swizzling 功能来自定义组件,你的网站的浏览体验完全由你来控制
  • 插件化
    • 使用基本模板构建你的网站,然后挑选并使用我们以及社区开发的功能
    • 开源您的插件并于合作伙伴共享,因为共享很重要
  • ✂️ 开发者体验
    • 数个模板可供选择,让你的网站初具雏形并能立即着手文档的编写
    • 统一的配置入口,让贡献者更易于维护
    • 有修改时,通过快如闪电的增量构建实现热加载
    • 基于路由的代码和数据拆分
    • 轻松发布到 GitHub Pages、Netlify 以及其它部署服务上

我们的共同目标是帮助您的用户快速找到他们所需要的,并更好地了解您的产品。借助从 Docusaurus 1 中获取的经验,我们将与您分享我们的最佳实践,以帮助您正确、良好地建立文档站点。

  • 🎯 SEO 友好
    • 为每个可能的路径生成静态 HTML 文件
    • 页面级的 SEO,帮助您的用户获取与问题直接相关的官方文档
  • 📝 Po 基于 MDX
    • 通过在 Markdown 中嵌入 JSX 和 React 来编写交互式组件
    • 在实时编辑器中共享您的代码,以使您的用户立即爱上您的产品
  • 🔍 搜索 - 你的整个站点皆可搜索
  • 💾 文档版本化 - 帮助你让文档与项目版本保持同步。
  • 🌍 i18n (即将推出)

Docusaurus 2 诞生的目的就是为您的所有用户提供友好的访问性,并且闪电般快速。

  • ⚡️ 快如闪电 - Docusaurus 2 遵循 PRPL 模式 可以确保您的内容闪电般地加载
  • 🦖 可访问性 - 专注可访问性,让所有用户都可以平等地访问你的网站

与其他工具的比较

在所有静态网站生成工具中,Docusaurus 都将重点放在文档网站上,并具有您需要的即用型结构。

我们还研究了其他主要的静态网站生成器,并希望分享我们在比较中的见解,希望能帮助您在繁琐的选择导航。

Gatsby

Gatsby 具有许多功能,具有丰富的插件生态系统,并且能够完成 Docusaurus 所做的一切。自然地,这是以更陡峭的学习曲线为代价的。Gatsby 在很多事情上做得很好,很适合构建多种类型的网站。另一方面,Docusaurus 试图将一件事情做得非常好,即成为编写和发布内容的最佳工具。

GraphQL 也是 Gatsby 的核心,尽管您不一定需要 GraphQL 来构建 Gatsby 站点。在大多数情况下,构建静态网站时,你不需要 GraphQL 提供的灵活性。

Docusaurus 2 在许多方面都受到了 Gatsby 的启发,并且 Gatsby 是一个很好的选择。

GitBook

GitBook has very clean design and has been used by many open source projects. With its focus shifting towards a commercial product rather than an open-source tool, many of its requirements no longer fit the needs as an open source project's documentation site. As a result, many have turned to other products. You may read about Redux's switch to Docusaurus here.

目前,GitBook 仅对开源和非营利团队免费。 而 Docusaurus 对所有人都免费。

Jekyll

ekyll 是圈内最成熟的静态网站生成器之一,并且已经成为一个很棒工具。实际上,在 Docusaurus 之前,Facebook 的大多数开源网站都是基于 Jekyll 构建的!Jekyll 入门非常简单。我们希望带来与使用 Jekyll 构建静态站点类似的开发人员体验。

与生成静态 HTML 并使用 <script /> 标签添加交互性相比,Docusaurus 网站其实是 React 应用程序。我们希望使用现代的 JavaScript 生态系统工具,为文档网站的性能、资源构建和优化以及易用性设置新标准。

VuePress

VuePress 与 Docusaurus 有很多相似之处,都专注于以内容为中心的网站,并且提供开箱即用的文档功能。但是,VuePress 时基于 Vue 构建的,而 Docusaurus 是基于 React 构建的。如果您想要一个基于 Vue 的解决方案,那么 VuePress 将是一个不错的选择。

随时了解

还缺少了什么?

如果您发现文档方面的问题或对总体上如何改进文档或项目有建议,请向我们提交 issue或发推时 @ 我们的 Twitter 账户 @docusaurus

对于新功能的需求,您可以在我们的 Canny board 上创建一个帖子,这是一个方便的路线图绘制工具(与难以分类的 GitHub issues 相比),并且可以按投票数进行排序,从而为核心团队提供了一个更好的指引,以发现哪些功能需求很高 。 不要对新功能(特别是大型功能)发出 Pull Request,因为有人可能已经在开发了,或者将成为我们路线图的一部分。 请先和我们沟通!