跳到主要内容

简介

免责声明#

虽然 Docusaurus v2 还是 alpha 版本 (从 2019 年中到现在),但是已经非常稳定了。

我们强烈建议你 使用 Docusaurus v2,放弃 Docusaurus v1

很多用户已经在使用 v2 版本了(趋势图),例如 React NativeRedux 等项目

如果您满足以下条件,则应使用 Docusaurus v2

  • ✅ 您希望拥有一个现代化的、基于 Jamstack 技术构建的文档站点
  • ✅ 您希望拥有一个支持客户端路由的单页应用(SPA)
  • ✅ 您希望获得 React 和 MDX 的所有功能
  • ✅ 您不需要支持 IE11
tip

通过 new.docusaurus.io 可以在 CodeSandbox 上测试 Docusaurus。

如果您是以下情况,请使用 Docusaurus v1

  • ❌ 您不需要一个单页应用(SPA)
  • ❌ 您更关注稳定性胜于更先进的技术
  • ❌ 您需要支持 IE11

更好的 Docusaurus 来了#

Docusaurus Slash Introduction

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,帮助您的用户随手获取与问题直接相关的官方文档
  • 📝 基于 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 的设计非常简洁,已被许多开源项目所使用。但是,随着其将重心从开源工具转向商业产品,它的许多限制已不再满足开源项目对文档站点的需求。其结果是,许多项目转向了其他产品。你可以在 这篇文章 中了解 Redux 切换到 Docusaurus 的原因。

目前,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,因为有人可能已经在开发了,或者将成为我们路线图的一部分。 请先和我们沟通!