Skip to main content
Version: 3.7.0

介绍

⚡️ 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 并按照教程操作。

tip

使用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：

对于希望升级到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 包含了许多功能，拥有丰富的插件生态系统，并且能够完成 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和交互性相比，Docusaurus网站是React应用程序。使用现代JavaScript生态系统工具，我们希望为文档网站的性能、资产构建管道和优化以及设置的简便性设定新的标准。

保持信息畅通​

缺少了什么？​

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

对于新功能请求，您可以在我们的功能请求板（Canny）上创建一个帖子，这是一个方便的工具，用于路线图规划，并允许按投票数排序，这为核心团队提供了一个更好的指标，显示哪些功能需求较高，相比之下，GitHub问题更难分类。请避免为新功能（尤其是大型功能）提交拉取请求，因为可能已经有人在处理它，或者它将成为我们路线图的一部分。先和我们谈谈！