Docusaurus 介绍
⚡️ Docusaurus 会帮助你在极短的时间内搭建一个漂亮的文档网站。
💸 自己造轮子是一件苦差事。 现在，你可以专注于内容创作，只需编写 Markdown 文件即可。
💥 想深入了解吗？ 来试试包括文档分版、国际化、自定义搜索、个性化主题在内的进阶功能特性吧！
💅 看看优秀的Docusaurus网站 来获得灵感，并读读一些其他人的使用感言吧 。
🧐 Docusaurus 是一款静态站点生成器。 我们释放了React的全部潜能，搭建了这一款有着快速客户端导航与交互性极佳的单页应用。 它提供了开箱即用的文档功能，不过也可用于搭建各种网站（个人网站、产品、博客、营销主页，等等）。
快速通道 ⏱️
边玩边学 Docusaurus，仅需 5 分钟！
创建一个新的 Docusaurus 网站，并跟随极短的内部教程。
安装 Node.js ，然后创建一个新的 Docusaurus 网站：
npx [email protected] my-website classic
运行网站：
cd my-website
npx docusaurus start
打开 http://localhost:3000 并遵循教程。
Use docusaurus.new to test Docusaurus immediately in your browser!
或者在线阅读5分钟教程
Docusaurus: 让文档变得易于上手
在 Algolia 社区活动 的演讲中，Meta Open Source 团队分享了Docusaurus的简短介绍。 他们介绍了如何上手项目，启用插件，并设置文档和博客等功能。
从 v1 {#migrating-from-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 组件，从而完全掌控网站的浏览体验
- 可扩展：
- 使用基础模板搭建网站，随后使用进阶功能及插件
- 开放你的插件源码，与社区共享
- ✂️ 开发者体验：
- 立即开始撰写你的软件文档
- 统一配置文件，贡献者可以轻松维护
- 热重载，飞速增量构建
- 基于路由的代码及数据拆分
- 轻松发布到 GitHub Pages、Netlify、Vercel 和其他部署服务
我们的共同目标——快速让用户找到需要的内容，并更好地了解你的产品。 我们和你分享我们的最佳实践，帮助你正确而优雅地构建自己的文档网站。
- 🎯 SEO 友好：
- 为每条路径静态生成 HTML 文件。
- 为每个页面做单独搜索引擎优化，帮助用户快速到达官方文档，解决当前问题。
- 📝 由 MDX 驱动：
- 用 JSX 和 React 撰写交互组件，并将其嵌入 Markdown。
- 在实时编辑器中分享你的代码，让你的用户迅速爱上你的产品。
- 🔍 搜索： 全站均可被搜索。
- 💾 文档分版：帮助你的文档与项目发布保持同步。
- 🌍 国际化 (i18n)：将你的网站翻译成多国语言。
Docusaurus 2 生而乐意为全体用户服务，而且快如闪电。
- ⚡️ 快如闪电： Docusaurus 2 遵循 PRPL 模式 来确保内容可以迅速加载。
- 🦖 无障碍访问 我们重视无障碍访问性，让所有用户都能平等地访问你的网站。
设计原则
- 易学。 Docusaurus 的 API 小而精，保证易于上手使用。 用户仍然可以完成大多数功能，即使需要花更多时间写更多代码。 没有抽象要比错误的抽象更好，我们不希望用户在错误的抽象上捣鼓解决方案。 必修课——最小化的 API 表面积。
- 直观。 用户查看 Docusaurus 项目目录或添加新特性时不会感到头昏脑胀。 软件应简单直观，用户则可轻松扩展。
- 客户端架构。 软件栈的分层（内容/主题/样式）应一目了然——充分抽象且模块化。
- 合理的默认设置。 常见、热门的性能优化选项会自动支持，并仍提供手动覆盖的方式。
- 不受约束。 用户无需使用默认插件或 CSS（虽然我们强烈推荐这么做）。 某些核心基础设施，例如 React Loadable 和 React Router 不能替换，因为我们基于这些做了默认性能优化，但更高层的架构则可以随意替换。 Markdown 引擎、CSS 框架、CSS 方法和其他架构的选择完全取决于用户。
我们相信，开发者足够了解一个应用库的运行原理，才能够更好地使用它。 因此，我们愿意花费精力来阐释 Docusaurus 的架构和各个组成部分，希望读者们可以拥有对它更深的理解，从而更熟练地使用它。
与其他工具 {#comparison-with-other-tools} 比较
在所有的静态网站生成器中，Docusaurus 独树一帜，专注于文档网站，拥有诸多开箱即用的功能。
我们同时也研究了其他一些主流静态站点生成器，想和你一起分享我们比较后的看法，希望能帮你在多种选择中做出判断。
Gatsby
Gatsby 包含了很多功能，有一个丰富的插件生态系统，并且能够做Docusaurus所做的一切。 当然，这带来了较陡的学习曲线。 Gatsby 在许多方面做得都很出色，适合构建许多类型的网站。 另一方面，Docusaurus 力图将一件事做到尽善尽美——成为最好的内容撰写与发布工具。
GraphQL 是 Gatsby 的核心，但搭建 Gatsby 网站不一定要用到它。 而在大多数静态网站中，你更不需要 GraphQL 所提供的灵活性。
Docusaurus 2 的许多方面都被 Gatsby 的出色之处所启发，这是一个优秀的替代品。
Docz 是一款用于构建文档网站的Gatsby主题。 它的功能与 Docusaurus 相比要匮乏。
Next.js
Next.js is another very popular hybrid React framework. 它可以帮助你构建出色的文档网站，但它并不着重于文档功能本身，而且需要你手动实现 Docusaurus 所自带的功能。
Nextra is an opinionated static site generator built on top of 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 is a popular Python static site generator with value propositions similar to Docusaurus.
如果你不需要单页应用，也不打算利用 React 的话，这是个好选择。
Material for MkDocs is a beautiful theme.
Docsify
Docsify makes it easy to create a documentation website, but is not a static-site generator and is not SEO friendly.
GitBook
GitBook has a very clean design and has been used by many open source projects. 但随着它把重点逐渐从开源工具转向商业产品，它不再符合开源项目文档网站的需要。 结果就是，许多项目转用了其他产品。 You may read about Redux's switch to Docusaurus here.
目前，GitBook 只对开源和非营利团队免费。 Docusaurus 则对所有人免费。
Jekyll
Jekyll is one of the most mature static site generators around and has been a great tool to use — in fact, before Docusaurus, most of Facebook's Open Source websites are/were built on Jekyll! 它的上手难度极低。 在静态网站构建方面，我们想要为你带来和 Jekyll 类似的开发者体验。
相比于静态生成 HTML，再通过 标签实现交互，Docusaurus 网站本身就是一个 React 应用。 我们希望借由现代化 JavaScript 生态系统工具，在文档站点性能、资源构建系统，优化和易部署性等领域制定新标准。
随时了解我们
缺点什么？
如果您发现了文档的问题或对如何改进文档或项目有建议，请向我们提交问题，或者发送一个提及@docusaurus 的推特。
对于新功能请求，你可以在我们的 (Canny) 需求管理板 上创建一个帖子。Canny 是一个方便的路线图管理工具，可以将需求按照赞同票数量降序排序，与 GitHub issue 相比，我们团队能够更好地了解什么新功能的需求更高，而 GitHub issue 更难标明这点。 请尽量避免提交新功能的合并请求 (Pull Request)，尤其是大改动，因为可能已经有人在着手实现它了，或者这个功能可能是我们未来规划的一部分。 总之，请先联系我们！