跳至主要内容
版本:3.5.2

简介

⚡️ Docusaurus 将帮助您**立即**构建一个**漂亮的文档网站**。

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

💥 想要了解更多?使用**高级功能**,例如版本控制、i18n、搜索和主题自定义。

💅 查看**最佳 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 和其他部署服务

我们的共同目标——帮助您的用户快速找到他们需要的内容,并更好地了解您的产品。我们分享我们的最佳实践,以帮助您正确且完善地构建您的文档网站。

  • 🎯 搜索引擎友好
    • 为每个可能的路径静态生成 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 构建静态网站的开发者体验。

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

保持知情

缺少内容?

如果您发现文档存在问题,或者对如何改进文档或项目本身有任何建议,请向我们提交问题,或发送推文提及@docusaurus Twitter 帐户。

对于新的功能请求,您可以在我们的功能请求板 (Canny)上创建一个帖子,这是一个方便的路线图工具,并允许按点赞数排序,这使核心团队能够更好地了解哪些功能需求量很大,与难以分类的 GitHub 问题相比。请勿为新功能(尤其是大型功能)创建拉取请求,因为可能有人已经在处理它或它将成为我们路线图的一部分。请先与我们联系!