发布 Docusaurus 2.0
今天我们非常高兴地终于宣布 Docusaurus 2.0！🥳️
在 Meta 开源，我们相信 Docusaurus 将帮助您以最少的努力构建最好的文档网站，让您专注于真正重要的事情：撰写内容。
经过四年努力，发布了 75 个 Alpha 版本 和 22 个 Beta 版本 后，Docusaurus 的下一代产品已准备好投入使用。从现在开始，我们计划遵守 语义化版本控制，并将更频繁地发布主要版本。
急着了解？请查看 Docusaurus 2.0 的新功能！
Docusaurus 究竟是什么？
Docusaurus 是一个静态站点生成器，可帮助您快速交付美观的文档网站。
专注于您的内容：只需编写 Markdown 文件。Docusaurus 将为您生成一个经过优化的网站，可以在任何地方轻松托管。
Docusaurus 功能齐全且高度灵活：我们提供精心设计的文档和博客布局，以及开箱即用的版本控制、搜索和国际化功能，并注重可访问性和搜索引擎优化。其灵活的主题系统允许调整用户界面以匹配您的品牌形象，使其与您的主网站或文档门户完美集成。它对 React 的使用实现了现代客户端导航，以及构建交互式文档的能力。
Docusaurus 的理念类似于帕累托法则：您可以用20% 的精力获得80% 的结果。这使您能够以最少的努力与顶级文档网站竞争。
除非您组建一个拥有工程资源的文档团队，否则您可能需要 Docusaurus！
Docusaurus 旨在成为最佳文档工具，但您也可以将其用于其他用例：博客、知识库、开发者作品集、第二大脑，甚至用于搭建登陆页面！
使用 Docusaurus 作为我的技术博客是一个绝佳的选择。它开箱即用，外观非常棒，而且出色的开发体验意味着我写得更多了
Docusaurus 背后的故事
Docusaurus 于2017 年在Facebook 开源（现为 Meta 开源）创建。我们有许多内部和开源项目需要文档。编写好的文档已经足够复杂，更不用说为美观的网站创建 HTML、CSS 和 JavaScript 了。我们希望项目负责人能够专注于内容，而Markdown 在这方面非常出色。
当时，我们的解决方案是一次又一次地复制/粘贴 Jekyll 模板。这自然变得难以维护，因此我们创建了一个工具来一劳永逸地解决我们自己的痛点。
它在 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。
我们的 GitHub 星标趋势非常积极，与主要框架竞争。
如今，Docusaurus v2 甚至在发布之前就已经取得了巨大成功。
我们现在到处都在使用 Docusaurus，并且非常喜欢它
我们从一月份就开始使用 V2，它一直都很棒
Docusaurus 在您的项目中为文档所需的一切提供了下一级别的便捷性。
Docusaurus 太棒了。我们正在使用它
2.0 有什么新功能？
Docusaurus v2 带来的每一项新功能都很难一一描述。让我们重点关注我们认为最有影响力的功能。
MDX
MDX 允许您在 Markdown 中交错使用 React 组件。这使您能够非常轻松地构建一流的交互式文档体验。
一个演示胜过千言万语。
### Give it a try: press that button!
import ColorModeToggle from '@theme/ColorModeToggle';
<ColorModeToggle/>
试一试：按下那个按钮！
MDX 拥有自己的插件系统。您可以自定义您的 Markdown 创作体验，甚至创建自己的 Markdown 语法。
Docusaurus + MDX 非常棒：我们能够实现一个漂亮的双窗格布局，并让作者对代码和相应散文的位置进行精细控制。
文件系统约定
我们的目标是让 Docusaurus 非常直观易用。我们添加了文件系统约定，添加文档页面就像创建一个 Markdown 文件一样简单。
使用自动生成的侧边栏使得创建页面变得如此简单，无需担心任何其他配置。
插件
Docusaurus 现在具有模块化架构和插件系统——我们的核心功能，如文档、博客、页面和搜索，都由独立的插件提供支持。
更重要的是，它使我们的社区能够通过附加功能增强 Docusaurus。
让我们重点介绍一些例子：
- redocusaurus：与 OpenAPI 和 Redoc 无缝集成
- docusaurus-preset-shiki-twoslash：使用 Shiki 代码块语法高亮和 TwoSlash TypeScript 编译器提示
插件 API 使用起来轻而易举，而且功能强大，我只用了几个小时就将 TypeScript 网站的代码示例渲染器移植了过来。
- docusaurus-search-local：内置 Algolia 插件的各种本地搜索替代方案之一
我们已在社区资源页面中精选了一系列杰出插件。
Docusaurus v2 中的插件系统让扩展 1Password 的开发者门户变得如此简单和有趣。非常兴奋能向你们展示我们正在开发什么。
主题
主题是 Docusaurus 最重要的功能之一：我们认为专业的文档网站应该尊重您公司的品牌形象并创造一致的体验。
Docusaurus 主题在多个层面提供了很大的灵活性：
- 自定义 CSS 变量以调整颜色、字体等。
- 提供您自己的 CSS 样式表。
- 从头开始实现您自己的主题。
- 覆盖我们默认主题提供的任何 React 组件：我们称之为篡改 (swizzling)。
我喜欢 Docusaurus 的 Swizzling 功能。它既有主见又灵活。这非常酷，因为一个框架通常需要牺牲其中一个。
这使得愿意投入更多时间进行自定义的用户能够构建外观独特的网站。
到目前为止，它运行得非常好。按照我们想要的方式进行样式设计真的很容易。完全没有障碍。
其他功能
Docusaurus 2 提供了非常长的有用功能列表：
- 主题：暗黑模式、更好的 UI 和 UX、灵活的
themeConfig选项…… - 文档版本控制：灵活的插件选项，以适应您的工作流程。
- 文档侧边栏：可折叠类别、类别索引页……
- 博客：多作者、作者映射、归档页面……
- Markdown：标签页、数学公式、实时代码块、链接、灵活的前置内容……
- 搜索：使用新的 Algolia DocSearch 3 体验。
- 资产：轻松集成图片和其他类型的文件。
- 国际化：配置选项、默认主题翻译……
- 可访问性：aria 标签、颜色对比度、跳过内容、键盘导航、渐进增强……
- SEO：合理的默认设置、易于自定义、规范 URL、社交卡片、禁止索引、站点地图、微数据、hreflang……
- PWA：为您的网站添加离线支持，并使其可安装。
- 快速失败：严格的配置验证、检测损坏的链接，并防止错误的生产部署。
- 支持配置文件的 TypeScript、插件、自定义页面和主题作者。
- 演练场：通过 docusaurus.new 轻松在浏览器中评估 Docusaurus。
- Canary 发布：使用 @canary npm 标签，在其他人之前使用即将发布的版本。
- 测试：Docusaurus 经过充分测试，我们内部使用功能并确保它们持续正常工作。
最近，我被 Docusaurus 开箱即用的出色表现震惊了。它超级稳定，配置恰到好处，不会让人感到不知所措，而且如果你比我更勇敢，还可以真正地自定义样式。
为什么是现在发布 2.0？
我们的许多热心追随者都很好奇为什么我们花了 4 年才发布 Docusaurus 2.0，考虑到 Beta 版已经成功且广泛用于生产环境。
原因是我们旨在遵守 语义化版本控制，这意味着每当我们发布破坏性变更时，我们都会增加主要版本号。
这很重要，原因如下：
- 它保证了简单的次要版本升级，只要您只使用公共 API。
- 它遵循前端生态系统惯例。
- 新的主要版本是彻底记录破坏性变更的机会。
- 新的主要/次要版本是通新博客文章传达新功能的机会。
问题在于，我们灵活的主题系统本身就创建了一个非常隐式的 API 表面，很难首先知道什么是破坏性变更。高度定制的 Docusaurus 网站有时在升级 Docusaurus 时会遇到困难，因为它们使用内部 API 实现了自定义。我们投入时间进行大量主题重构，并明确定义了我们的公共 API，以便将来更安全地进行代码更改。我们将继续扩展这个公共主题 API，以便最常见的网站自定义不需要使用任何内部 API。
从现在开始，Docusaurus 将更频繁地发布新的主要版本。实际上，您可以预期每 2 到 4 个月发布一个主要新版本。
主要版本号并非神圣不可侵犯，但我们仍然将破坏性变更分组，并避免过于频繁地发布主要版本。
有关详细信息，请查看我们的发布流程文档。
下一步是什么？
Docusaurus 3.0 的工作已经开始，这个下一个版本将在几个月后发布。我们将把向后兼容的更改回溯到 Docusaurus 2.x 的次要版本中，以便尽快通过稳定渠道向社区提供。
Docusaurus 即将发布的主要版本路线图上的功能示例：
- 升级到 MDX 2.0
- 改进 Markdown 基础设施
- 改进主题和篡改 (swizzle)
- TailwindCSS 主题
- 主题；支持导航栏、文档侧边栏、博客侧边栏、页脚的自定义项目类型
- 动态导航栏：导航栏项目激活策略
- 自定义社交卡片
- 支持 CSS-in-JS
- 使用 Node.js ES Modules
- 改进构建时间性能
- 扩展 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
