跳到主要内容

简介

⚡️ 道格龙（Docusaurus） 将帮助您在 短时间内创建一个漂亮的文档网站。

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

💥 准备好体验更多功能了吗？使用版本控制、国际化（i18n）、搜索和主题自定义等 高级功能。

💅 查看 最佳 道格龙（Docusaurus） 网站 以获取灵感。

🧐 道格龙（Docusaurus） 是一个 静态站点生成器。它构建了一个具有快速客户端导航的 单页应用 (SPA)，充分利用 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 component，完全控制您网站的浏览体验
  • 🔌 插件化：
    • 使用基本模板启动您的网站，然后使用高级功能和插件
    • 开源您的插件与社区分享
  • ✂️ 开发者体验：
    • 即刻开始编写您的文档
    • 通用的配置入口点，使贡献者更易于维护
    • 带有热重载（Hot reloading）功能，在更改时实现闪电般的增量构建
    • 基于路由的代码和数据拆分
    • 轻松发布到 GitHub Pages、Netlify、Vercel 和其他部署服务

我们的目标是——帮助您的用户快速找到他们需要的东西，并更好地了解您的产品。我们分享我们的最佳实践，以帮助您正确、良好地构建您的文档网站。

  • 🎯 SEO 友好：

    • 为每个可能的路径静态生成 HTML 文件。
    • 页面级 SEO 优化，可帮助您的用户直接访问与他们手头问题相关的官方文档。

  • 📝 由 MDX 驱动：

    • 通过嵌入在 Markdown 中的 JSX 和 React 编写交互式 component。

    • 在实时编辑器中分享您的代码，让您的用户当场爱上您的产品。

  • 🔍 搜索：您的整个网站都可搜索。

  • 💾 文档版本控制：帮助您保持文档与项目版本同步。

  • 🌍 国际化 (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） 以其成熟度、全面的功能集、灵活性和强大的社区而脱颖而出。它也正在定期 优化其基础设施 以在性能上保持竞争力。

联系我们​

还缺少什么吗？​

如果您发现文档有问题或有关于如何改进文档或整个项目的建议，请为我们 提交一个 issue，或发布一条提及 @docusaurus X 账户的推文。

对于新功能请求，您可以在我们的 功能请求页面 (Canny) 上创建一个帖子，这是一个方便的路线图工具，并允许按投票排序，这比难以分类的 GitHub issue 更能让核心团队了解哪些功能需求量大。 请不要为新功能（尤其是大型功能）创建拉取请求，因为可能已经有人在开发它或是我们路线图的一部分。请务必先与我们沟通！