简介
⚡️ 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 并按照教程操作。
使用 docusaurus.new 立即在浏览器中测试 Docusaurus！
或者在线阅读 5 分钟教程 。
Docusaurus：轻松创建文档
在 Algolia 社区活动 的此次演示中， Meta 开源团队 分享了 Docusaurus 的简要介绍。他们介绍了如何开始使用该项目、启用插件以及设置文档和博客等功能。
从 v1 迁移
Docusaurus v2+ 已从 Docusaurus v1 完全重写，充分利用了完全现代化的工具链。在 v2 正式发布 之后，我们强烈建议您 使用 Docusaurus v2+ 而不是 Docusaurus v1 ，因为 Docusaurus v1 已被弃用。
许多用户[/showcase] 已经在使用 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 文件。
- 页面特定的 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 的信息 here 。
目前，GitBook 仅对开源和非营利团队免费。Docusaurus 对所有人免费。
Jekyll
Jekyll 是最成熟的静态网站生成器之一，并且一直是一个很棒的工具——事实上，在 Docusaurus 之前，Facebook 的大多数开源网站都是/曾经基于 Jekyll 构建的！它非常易于上手。我们希望带来类似于使用 Jekyll 构建静态网站的开发体验。
与使用 <script /> 标记添加静态生成的 HTML 和交互性相比，Docusaurus 网站是 React 应用程序。通过使用现代 JavaScript 生态系统工具，我们希望在文档网站的性能、资产构建管道和优化以及易于设置方面树立新的标准。
保持知情
缺少什么？
如果您发现文档存在问题，或者对如何改进文档或项目本身有任何建议，请 向我们提交问题 ，或发送提及 @docusaurus X 帐户的推文。
对于新的功能请求，您可以在我们的 功能请求板 (Canny) 上创建帖子，这是一个方便的路线图工具，允许按点赞数排序，这使核心团队能够更好地了解哪些功能需求量很大，与难以分类的 GitHub 问题相比。避免为新功能（尤其是大型功能）创建拉取请求，因为有人可能已经在处理它，或者它将成为我们路线图的一部分。先和我们谈谈！