跳到主要内容

简介

⚡️ Docusaurus 能够帮助您快速创建一个 精美的文档网站。

💸 定制一套技术栈是非常昂贵的。相反，Docusaurus 让您 只需专注于内容，编写 Markdown 文件即可。

💥 准备好迎接更多功能了吗？还有版本控制、i18n、搜索和主题定制等 高级功能。

💅 借鉴 最好的 Docusaurus 网站 以获取灵感；还有更多 推荐您阅读的内容。

🧐 Docusaurus 是一款 静态网站生成器。它利用 React 的全部功能来构建具有快速客户端导航功能的 单页应用程序（single-page application），从而使您的网站具有交互性。它提供了开箱即用的 文档功能，也可用于创建 任何类型的网站（例如 个人网站、产品展示、博客、营销落地页面等）。

快速上手 ⏱️​

通过实操在 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 社区活动 的一次演讲中，Meta 开源团队 分享了 Docusaurus 的基本功能。包括如何上手该项目、 启用插件以及设置文档和博客功能等。

从 Docusaurus v1 升级​

Docusaurus v2+ 版本是基于最新的工具链对 Docusaurus v1 的全面重写。在 Docusaurus v2 正式发布 后，Docusaurus v1 就被淘汰了，因此我们强烈建议您使用 使用 Docusaurus v2+。

大量用户 已经在使用 Docusaurus v2+ 了（趋势图）。

如果您符合以下情况，请使用 Docusaurus v2+：

  • ✅ 您想要一个现代化的 Jamstack 文档网站
  • ✅ 您需要一个具有客户端路由功能的单页面应用程序 (SPA)
  • ✅ 您希望获得 React 和 MDX 的全部功能
  • ✅ 您不需要对 IE11 的支持

如果您符合以下情况，请使用 Docusaurus v1：

  • ❌ 您不需要单页面应用程序 (SPA)
  • ❌ 您需要支持 IE11（您确定吗？ IE 的 生命周期已经结束了，不再受官方支持了）

对于希望升级到 v2+ 的现有 v1 用户，您可以按照我们的 升级指南 进行升级。

卖点列表​

Docusaurus 高度关注开发者和贡献者的使用体验。

  • ⚛️ 用 💚 和 React 构建：
    • 利用 React 进行扩展和自定义
    • 利用您自己开发的 React 组件完全控制网站的浏览体验
  • 🔌 插件化:
    • 使用基本样板创建您的网站，然后探索 Docusaurus 的高级功能和插件吧
    • 开源您的插件，与社区共享
  • ✂️ 开发者体验:
    • 立马就能用来撰写您的文档
    • 统一的配置入口，让参与者更易维护
    • 支持热重载技术（Hot reloading），对更改进行闪电般的增量构建
    • 根据路由进行代码和数据的拆分
    • 轻松将网站发布到 GitHub Pages、Netlify、Vercel 以及更多服务上

我们的共同目标是帮助您的用户快速找到所需内容、更好地了解您的产品。通过分享我们的最佳实践，帮助您正确、出色地构建文档网站。

  • 🎯 搜索引擎友好：
    • 为每个可能的路径生成静态的 HTML 文件。
    • 页面级的搜索引擎优化，帮助用户直接访问与他们手头问题相关的官方文档。
  • 📝 Powered by MDX:
    • 通过嵌入到 Markdown 中的 JSX 和 React 编写交互式组件。
    • 在实时编辑器中演示您的代码，让您的用户当场爱上您的产品。
  • 🔍 搜索：您的整个网站都支持搜索功能。
  • 💾 文档版本管理：帮您保持文档与项目版本同步。
  • 🌍 国际化 (i18n)：将您的汪涵翻译成多种语言。

Docusaurus v2+ 的诞生是为了让您的所有用户都能轻松访问，而且速度快如闪电。

  • ⚡️ 快如闪电。Docusaurus v2+ 遵循 PRPL 模式，确保您的内容极速加载。
  • 🦖 无障碍（Accessible）。关注可访问性（accessibility），让所有用户都能平等地访问您的网站。

设计原则​

  • 简单易学。Docusaurus 应当易于学习和使用，API 非常少。即使用户需要花费更多的代码和时间来开发，但大多数功能还是可以实现的。没有抽象概念总比有错误的抽象概念要好，我们不希望用户不得不对错误的抽象进行 hack。Mandatory 访谈：最小化 API 接口。
  • 直观。当用户在查看 Docusaurus 项目的目录或添加新功能时不会感到不知所措。它应该看起来直观、易于在其基础上使用他们熟悉的方法进行构建。
  • 分层架构。我们的技术栈的每一层（内容/主题/样式）之间的关注点分离（separations of concerns）应具有清晰、良好的抽象和模块化。
  • 合理的默认设置。我们为用户提供通用且流行的性能优化和配置，但用户可以选择覆盖它们。
  • 不锁定供应商。用户无需使用默认插件或 CSS（虽然这是我们强烈推荐的）。某些核心基础架构（如 React Loadable 和 React Router）不能被替换，因为我们会对它们进行默认的性能优化，而更高层的架构不包括在内。Markdown 引擎、CSS 框架、CSS 方法论和其他架构的选择将完全由用户决定。

我们相信，作为开发人员，了解一个软件库的工作原理有助于我们更好地使用它。因此，我们花了很多精力来解释 Docusaurus 的架构和各个组件，希望用户在阅读后能对该工具有更深入的了解，并能更熟练地使用它。

与其他同类工具的对比​

在所有静态网站生成器中，Docusaurus 独一无二地专注于文档网站，并拥有许多开箱即用的功能。

我们还研究了其他主要的静态网站生成器，并希望与大家分享对比后的心得，希望能帮助大家在繁杂的选项中找到适合自己的产品。

Gatsby​

Gatsby 功能丰富，拥有丰富的插件生态系统，可以实现 Docusaurus 的所有功能。当然，这需要付出较高的学习成本。Gatsby 在很多方面都做得很好，适合构建多种类型的网站。不同的是，Docusaurus 只专注做好一件事：成为撰写和发布内容的最佳工具。

GraphQL 也是 Gatsby 的核心，不过你并不一定需要使用 GraphQL 来构建 Gatsby 网站。在大多数构建静态网站的情况下，你并不需要 GraphQL 所提供的灵活性。

Docusaurus v2+ 的许多方面吸取了 Gatsby 的优点，是一个不错的选择。

Docz 是一款用于构建文档网站的 Gatsby 主题。它目前的功能不如 Docusaurus。

Next.js​

Next.js 是另一个非常流行的混合型 React 框架。它可以帮助您构建一个良好的文档网站，但它并不是专门针对文档场景的，要实现如 Docusaurus 的开箱即用的功能还需要做更多的工作。

Nextra 是一款基于 Next.js 的静态网站生成器。目前，它的功能不如 Docusaurus 丰富。

VitePress​

VitePress 与 Docusaurus 有许多相似之处：都非常注重以内容为中心的网站，并提供开箱即用的文档相关功能。不过，VitePress 是基于 Vue 开发的，而 Docusaurus 则是基于 React 开发的。如果你想要一个基于 Vue 的解决方案，VitePress 将是一个不错的选择。

MkDocs​

MkDocs 是一款流行的、基于 Python 开发的静态网站生成器，其价值主张与 Docusaurus 相似。

如果您不需要单页面应用程序，也不打算使用 React，那么它是一个不错的选择。

Material for MkDocs 是 MkDocs 的一款精美的主题。

Docsify​

Docsify 可以轻松创建文档网站，但它不能生成静态网站，对搜索引擎优化（SEO）也不友好。

GitBook​

GitBook 的设计非常简洁，曾经被多开源项目所采用。然而，随着 GitBook 的重点转向成为商业产品而非开源工具，它的许多要求不再符合开源项目文档网站的需求。因此，许多项目转向了其他工具。您可以点击此处了解 Redux 转而使用 Docusaurus 的缘由。

现在，GitBook 只对开源和非营利团队免费。而 Docusaurus 则对所有人免费。

Jekyll​

Jekyll 是目前最成熟的静态网站生成器之一，也是一个非常好用的工具--事实上，在 Docusaurus 诞生之前，Facebook 的大部分开源网站都是/曾经是基于 Jekyll 构建的！Jekyll 上手非常简单。我们希望为开发者带来与使用 Jekyll 构建静态网站类似的体验。

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

常联系哟​

少了些什么？​

如果您发现文档中存在问题，或对如何改进文档或整个项目有自己的建议，请向我们 提交 issue，或发推时 @docusaurus 账户。

对于新的功能请求，您可以在我们的 功能需求板（Canny）上发帖。功能需求板（Canny）是一个用于绘制路线图的便捷工具，并允许根据投票结果进行排序，这能让核心团队更好地了解哪些功能需求量大，相对而言，GitHub 上的 issue 功能则难以统计。请避免为新功能（尤其是大型功能）提交 Pull Request，因为可能已经有人在做了，或者将成为我们路线图的一部分。务必请先与我们沟通！