跳到主要内容

简介

⚡️ Docusaurus 能够帮助你快速创建并发布 美观的文档网站

💸 自行搭建技术栈是非常昂贵的。而使用 Docusaurus 可以让你专注于内容 并只需编写 Markdown 文件即可。

💥 为更多功能做好准备了吗?大量 高级功能 (例如版本化、i18n、搜索和自定义主题)来了。

💅 请查看 最佳 Docusaurus 网站 列表以获得灵感,还有一些 用户心得 请做参考。

🧐 Docusaurus 是一个 静态网站生成器。它将你的网站构建成一个 单页面应用程序(single-page application),具有快速地客户端导航功能并充分利用了 React 的强大能力,为你的网站赋予更好地交互性。虽然 Docusaurus 是为 文档功能 而生的,但是也可以用来构建 任何类型的网站 (个人站点、产品介绍、博客、营销页面等)。

快速入门 ⏱️

通过亲自动手实践,5 分钟 内了解 Docusaurus!

跟随下面这个 非常简短的 教程,创建一个全新的 Docusaurus 网站吧。

安装 Node.js 并创建一个全新的 Docusaurus 网站:

npx create-docusaurus@latest my-website classic

启动网站:

cd my-website
npx docusaurus start

在浏览器中打开 http://localhost:3000 网址,并按照教程进行操作。

提示

通过 docusaurus.new 链接可以在你的浏览器中立即体验 Docusaurus!

或者在线阅读这个 5 分钟教程

Docusaurus:简化文档相关的工作

在以下这个 Algolia Community Event 视频中,Meta 开源团队 对 Docusaurus 作了简短的介绍,包括如何创建一个新的 Docusaurus 网站、使用插件、以及设置文档和博客等功能。

Migrating from v1

Docusaurus v2 has been a total rewrite from Docusaurus v1, taking advantage of a completely modernized toolchain. After v2's official release, we highly encourage you to use Docusaurus v2 over Docusaurus v1, as Docusaurus v1 has been deprecated.

大量用户 已经升级到或在使用 Docusaurus v2 了(趋势图)。

如果您满足以下条件,请使用 Docusaurus v2 :

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

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

For existing v1 users that are seeking to upgrade to v2, you can follow our migration guide.

特性

Docusaurus 高度重视开发者和贡献者的经验。

  • ⚛️ 不光有 💚 还有 React
    • 基于 React 扩展并自定义网站
    • 通过使用自己编写的 React 组件来掌控网站的浏览体验
  • 插件化
    • 先使用基本模板创建一个新站点,然后逐步使用高级功能和插件
    • 将你的插件开源并分享给社区
  • ✂️ 开发者经验
    • 立即开始文档创作
    • 统一的配置文件,让所有参与者容易上手
    • 支持热重载(Hot reloading)和超快速的增量构建
    • 代码和数据基于路由进行拆分
    • 轻松发布到 GitHub Pages、Netlify、Vercel 以及其它网站托管服务上

我们共同的目标是帮助您的用户快速找到他们需要的内容并更好地理解您的产品。我们利用我们掌握的最佳实践帮助您构建正确、良好的文档网站。

  • 🎯 对 SEO 友好
    • 为每个可能的路径生成静态 HTML 文件。
    • 页面级的 SEO,帮助你将用户引导到官方文档并直接进入针对具体问题的页面。
  • 📝 基于 MDX
    • 利用 JSX 和 React 编写交互式组件并嵌入到 Markdown 文档中。
    • 利用互动编辑器共享你的代码,让你的用户立即爱上你的产品。
  • 🔍 搜索: 整站支持搜索功能。
  • 💾 文档版本化: 帮你保持文档和项目版本的同步。
  • 🌍 国际化 (i18n): 将你的网站翻译成多种语言。

Docusaurus 2 is born to be compassionately accessible to all your users, and lightning-fast.

  • ⚡️ 闪电般的速度。 Docusaurus 2 遵循 PRPL 模式 ,让您的内容具有闪电般的加载速度。
  • 🦖 易于访问。 关注易用性,让所有用户都能平等地访问您的文档网站。

设计理念

  • 学习门槛低。 Docusaurus 没有太多的 API,这使其易于学习和使用。大多数事情都可以由用户自己实现,即便这需要用户编写较多的代码并花费更多时间。没有抽象优于错误的抽象,我们不希望用户在错误的抽象面前绕行。必看视频—最小化 API(Minimal API Surface Area)
  • 直观。 当查看 Docusaurus 项目的目录或添加新功能时,不会让用户感到不知所措。应当使用用户所熟悉的方法,并且看起来直观且易于扩展。
  • 分层架构。 架构(内容/主题/样式)中每层之间关注点分离(separations of concerns)应当具有清晰、良好的抽象和模块化。
  • 合理的默认值。 为用户进行常规和流行的性能优化和配置,并给用户预留修改的通道。
  • No vendor lock-in. 用户无需使用默认的插件或 CSS,但强烈建议使用。某些核心的基础架构(例如 React Loadable 和 React Router)是无法替换的,因为我们对其进行了底层的性能优化,其它抽象层及高的组件不受影响。对于 Markdown 解析引擎、CSS 框架、CSS 方法论以及其它组件都可以按用户的需求替换。

作为开发者,我们相信,了解工具的原理有助于更好地使用工具。因此,我们投入很大的力量编纂文档详细解释 Docusaurus 的架构以及各个组件,希望阅读此文档的用户能够对该工具有更深入的了解,并且能够更熟练的使用它。

与其他同类工具的对比

在所有静态网站生成工具中,Docusaurus 重点针对的是文档网站,并具有许多开箱即用的功能。

我们还研究了其它流行的静态网站生成器,以下是我们所作的比较,希望能帮助您做出合适的选择。

Gatsby

Gatsby 自带了许多功能,还拥有丰富的插件生态,能够完成 Docusaurus 所有的功能。当然,这是以更高的学习门槛为代价的。 Gatsby 在很多方面做的都很好,适合构建多种类型的网站。而 Docusaurus 的目标是把一件事做到完美 -- 成为编写和发布内容的最佳工具。

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

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

Docz 是一个针对文档网站的 Gatsby 主题。目前,它的功能不如 Docusaurus 完善。

Next.js

Next.js 是另一个非常流行的混合型 React 框架。它可以辅助你搭建一个好的文档网站,但对于具体到文档这一使用场景来说,要想实现匹配 Docusaurus 一样的开箱即用的功能的话,还需要做大量的开发工作。

Nextra 是一个建立在 Next.js 之上的、具有强制规则(opinionated )的静态网站生成器。目前,它的功能不如 Docusaurus 完善。

VuePress

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

MkDocs

MkDocs 是一个流行的、用 Python 开发的静态网站生成器,其价值主张类似于 Docusaurus。

如果你需要单页应用程序,也不打算用 React,那么,MkDocs 是一个很好的选择。

Material for MkDocs 是一个漂亮的主题。

Docsify

Docsify 让创建文档网站变得很容易,但它并不能生成静态的网站,对 SEO 也不友好。

GitBook

GitBook 页面涉及非常简洁,并且已经被许多开源项目所使用。随着其重心转向商业产品而非开源工具,其条款已经不再适合开源项目的文档网站了。因此,许多人转向了其它产品。你可以看看 Redux 从 GitBook 切换到 Docusaurus 的 心路历程

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

Jekyll

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

与生成静态 HTML 页面并通过 <script /> 标签加载 JavaScript 脚本来增加互动性相比,Docusaurus 生成的网站本质上是 React 应用程序。通过使用现代化的 JavaScript 生态工具,我们希望在文档站点的性能、构建、优化、设置上成为一个新的标杆。

随时了解最新信息

还缺少了什么?

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

对于新功能的需求,您可以在我们的 功能需求列表 (Canny) 上创建一个帖子,这是一个方便的需求管理工具,并且能够通过投票数(upvotes)进行排序,与难以分类的 GitHub issues 相比,这为核心团队提供了一个更好的指标,容易分辨哪些需求更强烈。不要对新功能(尤其是复杂的功能)直接提交 Pull Request,因为可能有人已经在开发了,或者将会成为我们路线图的一部分。有事儿您先说话!