跳转至主内容
Version: 2.0.0-alpha.75

介绍

声明#

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 简介

Docusaurus 1 曾经是一款纯开发文档网站生成器。 在 Docusaurus 2 中,我们从零开始重构。在保留 Docusaurus 1 易于上手、分版文档及国际化的长处同时,还为您带来了更多的自定义性。 (即将到来)

除此之外,Docusaurus 2 还是一款性能卓越的静态网站生成器,您还可用它来快速创建常见的内容驱动站点。(如开发文档、博客、产品着陆及营销页面)

虽然我们的重心仍是为您又快又好地呈现开发文档,但您也可以让 Docusaurus 2 如其他的 React 应用一般构建出任意类型的网站。 Docusaurus 现已可以构建任意类型的站点,不单单局限于开发文档网站。

特性#

Docusaurus 的主要重心位于您和贡献者之间的站点构建及维护体验。

  • ⚛️ 用 💚 使用 React 打造
    • 使用 React 扩展与自定义
    • 通过调和 (swizzling) 您的组件来完全掌控网站的浏览体验
  • 可扩展
    • 使用基础模板部署网站,随后选用由我们及社群所打造的扩展功能
    • 将您的插件开源给您的文档人,分享就是关爱
  • ✂️ 开发者体验
    • 自带多个部署模板,即刻编写您的文档
    • 统一配置文件可被轻松维护
    • 更改后飞速增量编译并热加载
    • 基于路由的代码及数据拆分
    • 轻松发布至 GitHub Pages、Netlify 及其他部署服务

我们的共同目标——快速让用户找到需要的内容,并更好地了解您的产品。 有了 Docusaurus 1 的前车之鉴,我们得以向您分享构建文档网站的最佳实践。

  • 🎯 SEO 友好
    • 为每条路径静态生成 HTML 文件
    • 指定页面 SEO 来帮助您的用户快速查阅官方以解决现有问题
  • 📝 MDX 驱动
    • 使用 JSX 及 React 撰写交互组件并嵌入 Markdown 文本
    • 在实时编辑器中分享您的代码让您的用户爱您所写
  • 🔍 搜索 - 全站均可被搜索
  • 💾 文档分版 - 帮助您的项目发行及文档保持同步
  • 🌍 i18n

Docusaurus 2 生而乐意为您的用户服务,而且快如闪电。.

  • ⚡️ 快如闪电 - Docusaurus 2 遵循 PRPL 模式来确保您的内容被快速加载
  • 🦖 无障碍 - 着重无障碍,所有用户均能轻松使用

与其他工具的对比#

在所有的静态网站生成器中,Docusaurus 特别专注于文档站点且拥有您所需的开箱即用结构。

我们还研究了其他主流的静态网站生成器并想与您分享我们的拙见,希望能帮助您从多种工具中做出选择。

Gatsby#

Gatsby 自带了诸多功能、拥有丰富的插件生态且足以胜任 Docusaurus 的所有功能。 当然,这带来了较高的学习曲线。 Gatsby 在许多方面做得都很出色,且适合构建许多类型的网站。 另一方面,Docusaurus 尝试将一件事做到尽善尽美——成为最好的内容撰写及发布工具。

GraphQL 是 Gatsby 的核心,虽然您并不需要它来构建一个站点。 在构建静态网站的多数情况下,您不需要 GraphQL 所提供的灵活性。

Docusaurus 2 的许多方面都被 Gatsby 的出色之处所启发,这是一个优秀的替代品。

GitBook#

GitBook 的设计简洁,同时被诸多开源项目所使用。 而随着其中心逐渐转向商业产品而非开源工具,它的许多需求不再符合一个开源项目网站的需要。 结果就是,许多项目转用了其他产品。 您也许在此处听说过 Redux 转投 Docusaurus 怀抱的事情。

目前,GitBook 仅向开源及非营利团队提供。 Docusaurus 则对所有人免费。

Jekyll#

Jekyll 是现有的一款成熟且优秀的静态网站生成器——实际上,在 Docusaurus 诞生之前,Facebook 的诸多开源站点都是使用 Jekyll 构建而成! 它的上手难度极低。 我们想要为您带来与使用 Jekyll 构建静态站点类似的开发者体验。

同静态生成的 HTML 及使用 <script /> 标签所添加的交互性相比,Docusaurus 站点为 React 应用程序。 我们希望借由现代化 JavaScript 生态系统工具,为文档站点性能、资源构建管道及优化和易部署性制定新标准。

VuePress#

VuePress 与 Docusaurus 都有着共同点——都非常专注于以内容为中心的网站,且都在安装后提供量身打造的文档特性。 但是,VuePress 由 Vue 驱动,而 Docusaurus 则是由 React 驱动。 若您想要基于 Vue 的解决方案,这将是您的不二之选。

保持更新#

缺点什么?#

若您发现文档问题或有改进文档或项目的建议,请向我们提出议题,或在 Twitter 上 @docusaurus

要提议新功能,您可以在我们的 Canny 板块上发帖。相较 GitHub 议案功能,此工具的点赞功能可让核心团队轻易了解高需求的功能特性,并做出项目的未来规划。 请尽量避免提交新功能的合并请求 (Pull Request),我们可能已有专人正在处理,或有可能此功能已经是我们未来规划的一部分。 总之,请先联系我们!