跳到主要内容

介绍

⚡️ Docusaurus 将帮助您立即发布一个美观的文档站点。

💸 构建自定义技术栈成本高昂。相反，专注于您的内容，只需编写 Markdown 文件。

💥 准备好了解更多？使用高级功能，如版本控制、国际化、搜索和主题自定义。

💅 查看**最佳 Docusaurus 站点**获取灵感。

🧐 Docusaurus 是一个静态站点生成器。它构建一个具有快速客户端导航的单页应用程序，充分利用 React 的全部功能使您的站点具有交互性。它提供开箱即用的文档功能，但可用于创建任何类型的站点（个人网站、产品、博客、营销着陆页等）。

快速上手 ⏱️​

通过实践在 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 的简要演练。他们介绍了如何开始使用该项目、启用插件以及设置文档和博客等功能。

从 v1 迁移​

Docusaurus v2+ 是对 Docusaurus v1 的完全重写，利用了完全现代化的工具链。在 v2 正式发布 后，我们强烈建议您使用 Docusaurus v2+ 而不是 Docusaurus v1，因为 Docusaurus v1 已被弃用。

很多用户 已经在使用 Docusaurus v2+（趋势）。

如果满足以下条件，请使用 Docusaurus v2+：

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

如果满足以下条件，请使用 Docusaurus v1：

  • ❌ 您不想要单页应用程序 (SPA)
  • ❌ 您需要支持 IE11（...真的需要吗？IE 已经停止支持，不再获得官方支持）

对于寻求升级到 v2+ 的现有 v1 用户，您可以遵循我们的迁移指南。

功能特性​

Docusaurus 在构建时高度关注开发者和贡献者体验。

  • ⚛️ 使用 💚 和 React 构建：
    • 使用 React 扩展和自定义
    • 通过提供您自己的 React 组件完全控制站点的浏览体验
  • 🔌 可插拔：
    • 使用基本模板引导您的站点，然后使用高级功能和插件
    • 开源您的插件与社区分享
  • ✂️ 开发者体验：
    • 立即开始编写您的文档
    • 通用配置入口点，使贡献者更易维护
    • 热重载，变更时闪电般快速的增量构建
    • 基于路由的代码和数据分割
    • 轻松发布到 GitHub Pages、Netlify、Vercel 和其他部署服务

我们的共同目标——帮助您的用户快速找到他们需要的内容，更好地理解您的产品。我们分享最佳实践，帮助您正确且出色地构建文档站点。

  • 🎯 SEO 友好：
    • 为每个可能的路径静态生成 HTML 文件。
    • 页面特定的 SEO，帮助您的用户直接访问与他们手头问题相关的官方文档。
  • 📝 由 MDX 驱动：
    • 通过嵌入在 Markdown 中的 JSX 和 React 编写交互式组件。
    • 在实时编辑器中分享您的代码，让您的用户立即爱上您的产品。
  • 🔍 搜索：您的整个站点都是可搜索的。
  • 💾 文档版本控制：帮助您保持文档与项目发布同步。
  • 🌍 国际化 (i18n)：将您的站点翻译成多种语言。

Docusaurus v2+ 生来就是为了对所有用户都具有同情心的可访问性，并且闪电般快速。

  • ⚡️ 闪电般快速。Docusaurus v2+ 遵循 PRPL 模式，确保您的内容加载极快。
  • 🦖 可访问。关注可访问性，使您的站点对所有用户都同样可访问。

设计原则​

  • 易于学习。Docusaurus 应该易于学习和使用，因为 API 相当小。大多数事情用户仍然可以实现，即使需要编写更多代码和花费更多时间。没有抽象比有错误的抽象更好，我们不希望用户必须绕过错误的抽象进行破解。必看演讲——最小 API 表面积。
  • 直观。用户在查看 Docusaurus 项目的项目目录或添加新功能时不会感到不知所措。它应该看起来直观且易于构建，使用他们熟悉的方法。
  • 分层架构。我们技术栈各层（内容/主题/样式）之间的关注点分离应该清晰——良好抽象且模块化。
  • 合理的默认值。常见和流行的性能优化和配置将为用户完成，但他们可以选择覆盖它们。
  • 无供应商锁定。用户不需要使用默认插件或 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 是一个美观的主题。

Docsify​

Docsify 使创建文档网站变得容易，但它不是静态站点生成器，对 SEO 不友好。

GitBook​

GitBook 设计非常简洁，被许多开源项目使用。随着其重点转向商业产品而非开源工具，其许多要求不再适合开源项目文档站点的需求。因此，许多人转向了其他产品。您可以在这里阅读 Redux 转向 Docusaurus 的情况。

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

Jekyll​

Jekyll 是最成熟的静态站点生成器之一，一直是一个很好的工具——事实上，在 Docusaurus 之前，Facebook 的大多数开源网站都是/曾经是基于 Jekyll 构建的！开始使用极其简单。我们希望带来与使用 Jekyll 构建静态站点类似的开发者体验。

与静态生成的 HTML 和使用 <script /> 标签添加交互性相比，Docusaurus 站点是 React 应用程序。使用现代 JavaScript 生态系统工具，我们希望在文档站点的性能、资产构建管道和优化以及易于设置方面设定新标准。

Rspress​

Rspress 是一个基于 Rspack（基于 Rust 的打包器）的快速静态站点生成器。它支持使用 MDX（带有 React 组件的 Markdown）编写内容、集成文本搜索、多语言支持 (i18n) 以及通过插件的可扩展性。专为创建优雅的文档和静态网站而设计，Rspress 生成易于部署的静态 HTML 文件。

Rspress 和 Docusaurus 非常相似。它们都有各自的优缺点。Rspress 创建得更晚，受益于现代基础设施，能够实现更快的站点构建。Docusaurus 以其成熟度、全面的功能集、灵活性和强大的社区而脱颖而出。它还定期现代化其基础设施，以在性能方面保持竞争力。

保持信息更新​

有什么遗漏吗？​

如果您发现文档有问题或对如何改进文档或项目有建议，请为我们提交问题，或发送推文提及 @docusaurus X 账户。

对于新功能请求，您可以在我们的功能请求板 (Canny) 上创建帖子，这是一个方便的路线图工具，允许按点赞数排序，这为核心团队提供了更好的指标来了解哪些功能需求量大，相比之下 GitHub 问题更难分类。避免为新功能（特别是大型功能）提交 Pull Request，因为可能已经有人在处理它或它将成为我们路线图的一部分。请先与我们交流！