简介
Docusaurus 能够帮助你建立并发布 美观的文档网站。
自行搭建技术栈是非常昂贵的。而使用 Docusaurus 可以让你专注于内容 并只需编写 Markdown 文件即可。
为更多功能做好准备了吗？大量 高级功能 （例如版本化、i18n、搜索和自定义主题）来了。
请查看 最佳 Docusaurus 网站 列表以获得灵感，还有一些 用户心得 请做参考。
Docusaurus 是一个 静态网站生成器。它发挥了 React 的全部功能来构建具有快速客户端导航的 单页应用，从而赋予你的网站交互性。它提供了开箱即用的 文档功能，还能用于创建 任何类型的网站 （例如个人网站、产品介绍、博客、营销页等等）。
快速入门
通过亲自动手实践，5 分钟 内了解 Docusaurus！
跟随下面这个 非常短的 教程，创建一个全新的 Docusaurus 网站。
安装 Node.js 并创建一个全新的 Docusaurus 网站：
npx @docusaurus/init@latest init my-website classic
启动网站：
cd my-website npx 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 是一个很好的选择。
Dokz 是一个针对文档型网站的 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，因为有人可能已经在开发了，或者将成为我们路线图的一部分。 请先和我们沟通！