跳到主要内容

简介

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

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

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

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

🧐 Docusaurus 是一个 静态网站生成器。它发挥了 React 的全部功能来构建具有快速客户端导航的 单页应用,从而赋予你的网站交互性。它提供了开箱即用的 文档功能,还能用于创建 任何类型的网站 (例如个人网站、产品介绍、博客、营销页等等)。

Docusaurus Slash Introduction

快速入门 ⏱️#

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

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

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

npx @docusaurus/init@latest init my-website classic

启动网站:

cd my-websitenpx docusaurus start

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

tip

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

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

免责声明#

虽然 Docusaurus v2 还是 beta 版本,但是已经非常稳定了,并且已被广泛使用。

由于 Docusaurus v1 即将被弃用,因此我们强烈建议你 使用 Docusaurus v2,放弃 Docusaurus v1

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

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

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

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

  • ❌ 您不需要使用单页应用(SPA)
  • ❌ 您需要支持 IE11

特性#

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

  • ⚛️ 用 💚 和 React 构建
    • 可利用 React 进行扩展和定制
    • 通过自己开发的 React 组件来完全控制站点的浏览体验
  • 插件化
    • 使用模板搭出网站的基本结构,然后添加高级功能和插件
    • 将您的插件开源并分享给社区
  • ✂️ 开发者体验
    • 无需过多步骤,立即开始编写文档
    • 统一的配置入口,让贡献者更易于维护
    • 文件有修改时,通过快如闪电的增量构建实现热加载
    • 代码和数据拆分皆基于路由
    • 轻松发布到 GitHub Pages、Netlify 以及其它部署服务上

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

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

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

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

设计理念#

  • 较少的学习 - Docusaurus 应当易于学习和使用,并且 API 要尽量少。即使需要用户花费更多的时间来编写代码,但大多数功能仍然可以由用户实现。没有抽象总比拥有错误的抽象好,而且我们不希望用户不得不绕过错误的抽象。 Mandatory talk - Minimal API Surface Area
  • 直观 - 当用户查看 Docusaurus 项目的目录或添加新功能时不会感到不知所措。Docusaurus 看起来应该直观且易于使用,并且采用用户所熟悉的方法。
  • 分层结构 - 软件系统中的每一层(内容/主题/样式)之间的关注点分离(separations of concerns,即 SoC)应具有清晰且良好的抽象、模块化。
  • 合理的默认值 - 默认为用户完成常见的和流行的性能优化和配置工作,但用户可以选择覆盖默认值。
  • 不锁定特定插件 - 尽管强烈建议用户使用默认插件或 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 构建的静态网站生成器。目前,Nextra 在功能上不如 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 切换到 Docusaurus 的原因。

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

Jekyll#

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

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

随时了解最新信息#

还缺少了什么?#

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

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