跳到主要内容
版本：Canary 🚧

Docusaurus 介绍

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

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

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

💅 Check the best Docusaurus sites for inspiration.

🧐 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 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 文件。
    • 为每个页面做单独搜索引擎优化，帮助用户快速到达官方文档，解决当前问题。
  • 📝 由 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 相比要匮乏。

VitePress​

VitePress 与 Docusaurus 有许多相似之处——都主要专注于以内容为中心的网站，并提供开箱即用的定制文档特性。 但是，VitePress 是由 Vue 驱动，而 Docusaurus 是由 React 驱动。 如果你想要一个基于 Vue 的解决方案，VitePress 是个不错的选择。

MkDocs​

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

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

Material for MkDocs 是一款很好看的主题。

Docsify​

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

GitBook​

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

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

Jekyll​

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

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

了解最新消息​

缺点什么？​

If you find issues with the documentation or have suggestions on how to improve the documentation or the project in general, please file an issue for us, or send a tweet mentioning the @docusaurus X account.

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