宣布 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 中的所有优点 : 文档、博客、页面、版本控制、国际化……
• 我们实现了几个新功能

更多详细信息请参见 Docusaurus 2 项目公告 和v1 到 v2 的迁移指南

谁在使用 Docusaurus 2.0？​

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

[! NPM 下载量：v2 超过 v1](https://npmtrends.com/docusaurus-vs-@docusaurus/core)

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

[! GitHub 星标：Docusaurus 处于有利地位](https://star-history.com/#facebook/docusaurus&vercel/next.js&gatsbyjs/gatsby&hexojs/hexo&nuxt/nuxt.js&vuejs/vuepress&11ty/eleventy&gohugoio/hugo&remix-run/remix&mkdocs/mkdocs&Timeline)

今天，即使在发布之前，Docusaurus v2 也已经取得了巨大的成功：

• 我们收到了许多精彩的推荐
• 1Password 和 Courier 等公司正在记录他们的积极体验
• 我们的 站点展示 参考了数百个站点，而这仅仅是冰山一角。

2.0 的新增功能？​

描述 Docusaurus v2 的每个新功能都很困难。让我们关注我们认为 最具影响力 的功能。

MDX​

MDX 允许您在 Markdown 中 交错 React 组件 。这使您可以非常轻松地构建一流的 交互式文档体验 。

演示胜过千言万语：

### 试一试：按一下那个按钮！

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：选项卡、数学公式、实时代码块、链接、灵活的前端配置……
• 搜索：使用新的 Algolia DocSearch 3 体验
• 资源：方便地整合图片和其他类型的文件
• 国际化：配置选项、默认主题翻译……
• 可访问性：aria 标签、颜色对比度、跳过内容、键盘导航、渐进增强……
• SEO：合理的默认值、易于自定义、规范 URL、社交卡片、no-index、站点地图、微数据、hreflang……
• PWA：为您的网站添加离线支持，并使其可安装
• 快速失败：严格的配置验证、检测损坏的链接并防止错误的生产部署
• 对配置文件、插件、自定义页面和主题作者的 TypeScript 支持
• 游乐场：使用 docusaurus.new 从浏览器轻松评估 Docusaurus
• Canary 版本：使用 @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 开源项目的 Docusaurus 2.0 项目
• Paul O’Shannessy 支持 Meta 开源项目所有后续版本的 Docusaurus 的开发
• Eric Nakagawa 创建了我们最可爱的吉祥物 Slash
• Endilie Yacop Sucipto 为其对Docusaurus v2 的重要早期工作
• Clément Vannicatte 、 Kevin Granger 和整个 Algolia 团队的支持
• 所有社区成员为做出宝贵的代码贡献、改进我们的文档以及在 Discord 上解答问题

我们要特别感谢所有 Docusaurus 2.0 的早期采用者 ，感谢他们评估其 alpha、beta 和 canary 版本，并提供大量 宝贵的反馈 。我们真诚地希望您在使用它时拥有良好的体验，并且您将继续为即将发布的 Docusaurus 3.0 预发布版本提供反馈。

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

现在，让您的想象力自由驰骋吧 🤪!

— Slash

我们正在 ProductHunt 和 Hacker News 上！

🙏 分享您使用 Docusaurus 的经验与社区！