Skip to main content
版本：3.1.1

Docusaurus 介绍

⚡️ Docusaurus 会帮助你在极短的时间内搭建一个漂亮的文档网站。

💸 自己造轮子是一件苦差事。现在，你可以专注于内容创作，只需编写 Markdown 文件即可。

💥 想深入了解吗？来试试包括文档分版、国际化、自定义搜索、个性化主题在内的进阶功能特性吧！

💅 看看**优秀的Docusaurus网站** 来获得灵感，并阅读一些其他人的**使用感言**吧 。

🧐 Docusaurus 是一款静态站点生成器。我们释放了React的全部潜能，搭建了这一款有着快速客户端导航与交互性极佳的单页应用。它不仅提供了开箱即用的文档功能，也可用于搭建各种类型的网站（个人网站、产品、博客、营销主页等等）。

快速通道 ⏱️​

边玩边学 Docusaurus，仅需 5 分钟！

创建一个新的 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 Open Source 团队分享了 Docusaurus 的简短介绍。他们介绍了如何上手项目，启用插件，并设置文档和博客等功能。

从 v1 迁移​

Docusaurus v2+ 在 v1 基础上完全重写了内部逻辑，采用了一套完全现代化的工具链。在 v2正式发布 之后，我们强烈建议您 使用 Docusaurus v2+ 而不是 Docusaurus v1，因为 Docusaurus v1 已被弃用。

许多用户已经在使用 Docusaurus v2+ 了(trends)。

如果你有以下需求，请使用 Docusaurus v2+：

  • ✅ 你想要一个现代化的 Jamstack 文档网站
  • ✅ 你想要自带客户端路由的单页应用 (SPA)
  • ✅ 你想要发挥 React 和 MDX 的全部功力
  • ✅ 你不需要支持 IE11

如果你有以下需求，请使用 Docusaurus v1：

  • ❌ 你不需要单页应用 (SPA)
  • ❌ 你需要支持 IE11 （……你真的需要吗？ IE 生命周期已经结束，不再得到官方支持)

对于正在考虑升级到 v2+ 的现有的 v1 用户，你可以参考我们的迁移指南。

特性​

Docusaurus 从设计之初就极度重视开发者及贡献者的体验。

  • ⚛️ 用 💚 和 React 打造：
    • 使用 React 实现扩展与自定义
    • 提供你自己的 React 组件，从而完全掌控网站的浏览体验
  • Pluggable:
    • 使用基础模板搭建网站，随后使用进阶功能及插件
    • 开放你的插件源码，与社区共享
  • ✂️ 开发者体验：
    • 立即开始撰写你的软件文档
    • 统一配置文件，贡献者可以轻松维护
    • 热重载，飞速增量构建
    • 基于路由的代码及数据拆分
    • 轻松发布到 GitHub Pages、Netlify、Vercel 和其他部署服务

我们的共同目标——快速让用户找到需要的内容，并更好地了解你的产品。我们和你分享我们的最佳实践，帮助你正确而优雅地构建自己的文档网站。

  • 🎯 SEO 友好：
    • 为每条路径静态生成 HTML 文件。
    • 为每个页面做单独搜索引擎优化，帮助用户快速到达官方文档，解决当前问题。
  • 📝 由 MDX 驱动：
    • 用 JSX 和 React 撰写交互组件，并将其嵌入 Markdown。
    • 在实时编辑器中分享你的代码，让你的用户迅速爱上你的产品。
  • 🔍 搜索： 全站均可被搜索。
  • 💾 文档分版：帮助你的文档与项目发布保持同步。
  • 🌍 国际化 (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 的核心，但搭建 Gatsby 网站不一定要用到它。而在大多数静态网站中，你更不需要 GraphQL 所提供的灵活性。

Docusaurus v2+ 的许多方面都被 Gatsby 的出色之处所启发，这是一个优秀的替代品。

Docz 是一款用于构建文档网站的 Gatsby 主题。它的功能与 Docusaurus 相比要匮乏。

Next.js​

Next.js 是另一款极为热门的 React 混合框架。它可以帮助你构建出色的文档网站，但它并不着重于文档功能本身，而且需要你手动实现 Docusaurus 所自带的功能。

Nextra 是一个基于 Next.js 构建的静态站点生成器。它的功能与 Docusaurus 相比要匮乏。

VuePress​

VuePress has many similarities with Docusaurus - both focus heavily on content-centric website and provides tailored documentation features out of the box. 但是，VuePress 是 Vue 驱动的，而 Docusaurus 则是 React 驱动的。如果你想要一个基于 Vue 的解决方案，VuePress 是个不错的选择。

MkDocs​

MkDocs 是一款受欢迎的 Python 静态站点生成器，其设计理念与 Docusaurus 类似。

如果你不需要单页应用，也不打算利用 React 的话，这是个好选择。

Material for MkDocs 是一个漂亮的主题。

Docsify​

Docsify 让你能轻松创建文档网站，但它并不是一款静态网站生成器，而且对搜索引擎不太友好。

GitBook​

GitBook 的设计清爽，诸多开源项目都在使用。但随着它把重点逐渐从开源工具转向商业产品，它不再符合开源项目文档网站的需要。结果就是，许多项目转用了其他产品。你可以从这里了解 Redux 切换 Docusaurus。

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

Jekyll​

在市面上的静态网站生成器中，Jekyll 是最成熟而优秀的之一——实际上，在 Docusaurus 诞生之前，Facebook 的绝大多数开源站点都是用 Jekyll 构建的！它的上手难度极低。在静态网站构建方面，我们想要为你带来和 Jekyll 类似的开发者体验。

相比于静态生成 HTML，再通过 标签实现交互，Docusaurus 网站本身就是一个 React 应用。我们希望借由现代化 JavaScript 生态系统工具，在文档站点性能、资源构建系统，优化和易部署性等领域制定新标准。

了解最新消息​

缺点什么？​

如果您发现文档存在的问题或对如何总体改进文档或项目有建议； 请为我们提交一个issue，或发送一个提及@docusaurus X账户的推文。

对于新功能请求，你可以在我们的 (Canny) 需求管理板 上创建一个帖子。Canny 是一个方便的路线图管理工具，可以将需求按照赞同票数量降序排序，与 GitHub issue 相比，我们团队能够更好地了解什么新功能的需求更高，而 GitHub issue 更难标明这点。请尽量避免提交新功能的合并请求 (Pull Request)，尤其是大改动，因为可能已经有人在着手实现它了，或者这个功能可能是我们未来规划的一部分。总之，请先联系我们！