宣布 Docusaurus 2.0

今天，我们非常高兴终于宣布 Docusaurus 2.0！🥳️

在 Meta 开源 中，我们相信 Docusaurus 将帮助您以最小的努力构建最佳文档网站，让您专注于真正重要的事情：编写内容。

经过4 年的努力，75 个 Alpha 版本 和 22 个 Beta 版本，下一代 Docusaurus 已准备好迎接黄金时代。从现在开始，我们计划遵守 语义版本控制，并更频繁地发布主要版本。

我们已在 ProductHunt 和 Hacker News 上发布！

现在是表达您对 Docusaurus 的爱的最佳时机！

Docusaurus 到底是什么？​

Docusaurus 是一个静态网站生成器，可帮助您在短时间内构建漂亮的文档网站。

专注于您的内容：只需编写Markdown 文件。Docusaurus 将为您生成一个优化的网站，该网站易于在任何地方托管。

Docusaurus 功能齐全且灵活：我们提供精心设计的文档和博客布局，以及开箱即用的版本控制、搜索和国际化功能，并呼吁可访问性和搜索引擎优化。其灵活的主题系统允许调整 UI 以匹配您的品牌，使其与您的主要网站或文档门户网站完美集成。它使用React，使现代的客户端导航成为可能，并能够构建交互式文档。

Docusaurus 的理念类似于帕累托法则：您可以以 20% 的努力获得80% 的结果。这使您能够以最小的努力与顶级文档网站竞争。

Docusaurus 旨在成为最佳文档工具，但您也可以将其用于其他用例：博客、知识库、开发者资料库、第二大脑，甚至用于搭建登录页面！

Docusaurus 背后的故事​

Docusaurus 是在2017 年的Facebook 开源（现为 Meta 开源）中创建的。我们有很多内部和开源项目需要记录。编写优质文档已经足够复杂，更不用说为美观的网站创建 HTML、CSS 和 JavaScript 了。我们希望项目负责人能够专注于内容，而Markdown非常适合此目的。

当时，我们的解决方案是一遍又一遍地复制/粘贴 Jekyll 模板。这自然会变得难以维护，因此我们创建了一个工具来一次性解决我们自己的痛点。

Docusaurus v1 诞生了!

它迅速在 Facebook 和前端生态系统中获得动力，被许多流行的项目采用，例如 Prettier、Babel、React-Native、KaTeX，当然还有 Docusaurus v1 本身。

迈向 Docusaurus 2.0​

Docusaurus v1 非常成功，但我们开始质疑一些架构设计

• React 仅用作服务器端模板语言，而不是在客户端使用
• 主题系统非常有限，除了用 CSS 更改一些颜色之外，很难进行更高级的定制
• 文档版本控制系统令人困惑，因为它基于差异算法
• 代码库是单体的，既没有经过充分测试，也不易于扩展

Docusaurus v2 是从头开始使用新的模块化架构重建的

• React 现在也用于客户端，使现代单页应用程序导航成为可能
• 插件使社区能够以第三方软件包的形式贡献有用的功能
• 主题比以往任何时候都更灵活
• 文档版本控制现在基于快照副本，更容易理解
• 我们保留了 v1 中的所有优点：文档、博客、页面、版本控制、i18n…
• 我们实现了几个新功能

更多详情请参见 Docusaurus 2 项目发布公告 和 v1 到 v2 迁移指南

谁在使用 Docusaurus 2.0？​

尽管处于预发布阶段，但Docusaurus v2 在 NPM 下载量方面很快就超过了 Docusaurus v1

我们的 GitHub 星标趋势非常积极，与主要框架竞争

如今，即使在正式发布之前，Docusaurus v2 也已取得巨大成功

• 我们收到了许多 令人愉快的评价
• 像 1Password 和 Courier 这样的公司正在记录他们积极的体验
• 我们的 网站展示 参考了数百个网站，这只是冰山一角。

2.0 中的新增功能？​

很难描述 Docusaurus v2 中的所有新功能。让我们重点关注我们认为 **最有影响力** 的功能。

MDX​

MDX 允许您在 Markdown 中 **插入 React 组件**。这使您能够非常轻松地构建顶级的 **交互式文档体验**。

一张图胜过千言万语

### Give it a try: press that button!

import ColorModeToggle from '@theme/ColorModeToggle';

<ColorModeToggle/>

文件系统约定​

我们的目标是使 Docusaurus 非常 **直观** 使用。我们添加了文件系统约定，添加文档页面就像创建 Markdown 文件一样简单。

插件​

Docusaurus 现在拥有一个 **模块化架构**，带有一个插件系统——我们的 **核心功能**，例如文档、博客、页面和搜索，都是由单个插件驱动的。

更重要的是，它使我们的社区能够 **增强 Docusaurus**，添加更多功能。

让我们重点介绍一些示例

• redocusaurus：与 OpenAPI 和 Redoc 的无缝集成

• docusaurus-preset-shiki-twoslash：使用 Shiki 代码块语法高亮，以及 TwoSlash TypeScript 编译器提示

• docusaurus-search-local：内置 Algolia 插件的各种本地搜索替代方案之一

主题​

主题是 Docusaurus 最重要的功能之一：我们认为专业文档网站应该 **尊重您公司的品牌** 并创建一个一致的体验。

Docusaurus 主题在多个层面上提供了很大的 **灵活性**

• 自定义 CSS 变量以调整颜色、字体等
• 提供您自己的 CSS 样式表
• 从头开始实现您自己的主题
• **覆盖默认主题提供的任何 React 组件**：我们称之为 swizzling

这使愿意在 **自定义** 上投入更多时间的用户能够构建与其他网站 **外观不同** 的网站。

其他功能​

Docusaurus 2 带有非常长的实用功能列表

• 主题：暗模式、更好的 UI 和 UX、灵活的 themeConfig 选项...
• 文档版本控制：灵活的插件选项以适应您的工作流程
• 文档侧边栏：可折叠类别、类别索引页面...
• 博客：多个作者、作者地图、归档页面...
• Markdown：选项卡、数学方程式、实时代码块、链接、灵活的前置 matter...
• 搜索：使用新的 Algolia DocSearch 3 体验
• 资产：轻松地将图像和其他类型的文件整合进来
• 国际化：配置选项、默认主题翻译...
• 无障碍性：aria 标签、颜色对比度、跳至内容、键盘导航、渐进增强...
• SEO：明智的默认值、易于自定义、规范 URL、社交卡片、no-index、网站地图、微数据、hreflang...
• PWA：为您的网站添加离线支持，并使其可安装
• 快速失败：严格的配置验证、检测损坏的链接，并防止出现错误的生产部署
• 对配置文件、插件、自定义页面和主题作者的支持
• 游乐场：使用 docusaurus.new 从您的浏览器轻松评估 Docusaurus
• 金丝雀发布：使用 @canary npm 标签在任何人之前使用即将发布的版本
• 测试：Docusaurus 经过良好测试，我们会对功能进行狗食测试，并确保它们继续正常工作

为什么现在是 2.0？​

我们许多热情的粉丝都很好奇 **为什么我们花了 4 年时间才发布 Docusaurus 2.0**，考虑到 beta 版已经成功，并且 **在生产环境中被广泛使用**。

原因是我们旨在 **尊重 语义版本控制**，这意味着只要我们发布 **重大更改**，我们就会增加主版本号。

这在很多方面都很重要

• 它 **保证了简单的次要版本升级**，只要您只使用 公共 API
• 它遵循前端生态系统约定
• 新主版本是彻底记录重大更改的机会
• 新主/次版本是通过博客文章传达新功能的机会

问题是，我们灵活的主题系统本质上创建了一个非常 **隐式的 API 表面**，很难一开始就知道什么是重大更改。高度自定义的 Docusaurus 网站有时很难升级 Docusaurus，因为它们使用内部 API 来实现自定义。我们投入时间进行了广泛的主题重构，并明确定义了我们的 公共 API，以便将来可以更安全地进行代码更改。我们将继续扩展此公共主题 API，以便最常见的站点自定义不需要使用任何内部 API。

下一步是什么？​

Docusaurus 3.0 的工作已经开始，这个下一个版本将在几个月内发布。我们将 **在 Docusaurus 2.x 次要版本中回溯兼容更改**，以便尽快通过稳定渠道提供给社区。

Docusaurus 未来主要版本的路线图上的一些功能示例

• 升级到 MDX 2.0
• 改进 Markdown 基础设施
• 改进主题和 swizzle
• TailwindCSS 主题
• 主题；支持导航栏、文档侧边栏、博客侧边栏、页脚的自定义项目类型
• 动态导航栏：导航栏项目激活策略
• 自定义社交卡片
• CSS-in-JS 支持
• 使用 Node.js ES 模块
• 提高构建时间性能
• 扩展 Docusaurus 插件、CMS 集成

感谢您​

我们要感谢 我们所有贡献者，包括

• Docusaurus 核心团队：Alexey Pyltsyn、Joshua Chen、Sébastien Lorber、Yangshun Tay 以及我们所有 前团队成员
• Joel Marcey 创建了 Docusaurus 1.0，并在 Meta Open Source 中支持 Docusaurus 2.0 项目
• Paul O’Shannessy 在 Meta Open Source 中支持所有后续 Docusaurus 版本的开发
• Eric Nakagawa 为我们创造了最可爱的吉祥物 Slash
• Endilie Yacop Sucipto 为他 对 Docusaurus v2 的最初工作 做出了重大贡献
• Clément Vannicatte、Kevin Granger 以及整个 Algolia 团队对我们的支持
• 所有社区成员，感谢他们做出了宝贵的代码贡献、改进我们的文档，并在 Discord 上解答问题

我们特别感谢所有Docusaurus 2.0 的早期采用者，感谢你们对 alpha、beta 和 canary 版本的评估，并提供了大量宝贵的反馈。我们真诚地希望你们使用 Docusaurus 2.0 有着很棒的体验，并且希望你们能够继续为即将发布的 Docusaurus 3.0 预览版提供反馈。

在 Meta 开源 中，Docusaurus 是我们最成功的项目之一。我们迫不及待地想看到你们将要创建的所有优秀的文档网站！不要忘记将它们提交到我们的网站展示!

现在，让你的想象力尽情发挥吧 🤪!

— Slash

我们已在 ProductHunt 和 Hacker News 上发布！

🙏 与社区分享你使用 Docusaurus 的体验!