likes
comments
collection
share

🎉 dumi 2，它来了它来了它来了

作者站长头像
站长
· 阅读数 15

🎉 dumi 2，它来了它来了它来了

dumi 1.0 在 2020 年 3 月 2 日正式发布，到今天一共有 80+ 位 Contributor、提交 1100+ Commit、为近 4000 个开源项目提供了组件库/站点的文档方案；dumi 作为一个 GitHub 数亿开源项目中的渺小一粒，能有这么多人共同参与、能为这么多项目提供价值，无疑是十分幸运的。

与这份幸运一同到来的，还有许多体验问题的反馈、组件研发的思考、实际项目的场景，加上社区的底层技术栈也在飞速迭代，是时候给 dumi 做一次大升级了，所以我们在今年的 7 月 29 日正式启动了 dumi 2.0 的研发，而在今天，它终于与大家正式见面了！

核心升级

全新主题系统

先晒一下全新的默认主题，它也是主题系统的一部分：

🎉 dumi 2，它来了它来了它来了

除了更精致以外，dumi 2 的主题系统还提供了如下能力。

主题支持局部覆盖

在 dumi 1 里，想定制侧边栏就必须覆盖整个 Layout，成本非常高； dumi 2 参考 Docusaurus 的 Swizzing 设计、提供了 slots（UI 插槽）特性，只需要在项目里创建 .dumi/theme/slots/{SlotName} 就能实现对应 slot 的局部覆盖，并且提供哪些 slots 是由主题包决定的，在保持开放性的同时、极大地降低了定制成本。

自带国际化方案

在 dumi 1 里，主题包想做多语言，只能自行判断 locale 展示不同的文案； dumi 2 约定主题包内的 locales/{lang-LOCALE}.json 文件为国际化文案，会被框架自动加载，主题包组件只需要从 dumi 里导出 react-intl的相关 API，只需调用文案 key 即可实现文案的国际化。 不仅如此，文案也是支持 key 覆盖的，这意味着用户如果想定制主题包提供的文案，只需要创建 .dumi/theme/locales{lang-LOCALE}.json 覆盖对应 key 的文案即可。

支持注册 dumi 插件

主题包可能伴随着默认配置、甚至是框架能力扩展，所以 dumi 2 约定主题包的 plugin.ts 或 plugin/index.ts 为主题包的插件、会自动挂载，为主题包提供更加强大的定制能力。

更多信息欢迎移步官方文档查看：主题-如何工作。

内置全文搜索

静态站点的搜索一直是老大难的问题，社区一般就两种方案：

  1. 传统的标题搜索方案，因为生成 TOC 原本就需要采集标题，拿来做索引是顺理成章的，这也是 SSG 框架的常见做法，缺点是能搜到的东西太少
  2. 接入三方的搜索服务并且产出预渲染的 HTML 和 sitemap.xml，好处是能保证搜索质量，缺点是有一定门槛，例如 Algolia 就需要申请 AppKey

听起来都不完美，但 dumi 2 这次带来了第 3 种方案，既不需要接入三方服务、又能实现全文匹配、还不会导致产物尺寸增加，是真正开箱即用的全文搜索方案！

🎉 dumi 2，它来了它来了它来了

搜索的过程在 Service Worker 中进行，这意味着不需要担心搜索结果匹配引发性能问题、也可以离线部署，同时 dumi 也提供了搜索 API、可供主题包定制搜索结果的呈现。

约定式路由增强

dumi 1 被诟病最多的问题就是『路由生成难以控制』，配置完不跑一跑都不知道长什么样儿，所以 dumi 2 这次对约定式路由做了 3 大升级。

配置简化

去掉 Markdown FrontMatter 中的 nav.path 和 group.path 配置项，最终路由就是文件路径，简单明了。

概念拆分

将路由分为『文档路由』和『资产路由』，文档路由通常放在 docs 目录下，会嵌套层级，而资产路由通常放在 src 下，不会嵌套层级、且默认归类在某一前缀（比如 /components）下，比如：

docs/guide/getting-started.md 会生成 /guide/getting-started
src/Foo/index.md 会生成 /components/foo

以上解析路径和资产路由前缀均可通过配置修改。

约定式 Tab

支持以约定式的形式为 Markdown 内容增加 Tab，比如 index.$tab-key.md 就会作为 index.md 的 Tab 呈现，可以帮助我们更好地组织文档内容的呈现：

🎉 dumi 2，它来了它来了它来了

不仅如此，Tab 也支持通过插件 API 注册，为更多功能的扩展提供了可能。

更好的编译性能

dumi 2 通过结合使用 Umi 4 MFSU、esbuild、SWC、持久缓存等方案，带来比 dumi 1 更快的编译速度。

另外，dumi 2 也使用最新的 Unified.js 生态重写了整个 Markdown 编译逻辑，还提供了对 remark 和 rehype 插件的配置能力，在高性能的同时也更加易于定制。

成为合格的 SSG

dumi 1 虽然本质上是 SSG（Static Site Generator），但实际上是异常偏科的，这次把本职工作勉强做合格：

  1. 支持页面级的 TDK 配置，且内置 Helmet 可做深度自定义
  2. 内置 404 页面
  3. 默认静态化全部页面
  4. 支持基于 React@18 Stream 的构建时预渲染
  5. ……

当然合格仍然是不够的，也希望大家能一起参与完善，既然是『为组件研发而生的静态站点框架』，那就组件研发和静态站点都不能落下。

终于『有面儿』了

回想起当初 dumi 取名的过程，还是觉得很神奇，一个代号可以是冰冷的字母，也可以是有温度的昵称。

不过这么久以来，dumi 一直都借用的 Umi 的 LOGO，是时候趁着 2.0 的全新升级，给这个有温度的昵称配上一张有温度的脸庞了：

🎉 dumi 2，它来了它来了它来了

这就是 dumi 的 LOGO，用扎实的文档撑起精致的组件，请记住它的模样，如果是脸盲就不强求了 :D

除了以上核心升级，dumi 2.0 还有非常多的细节改进，受限于篇幅就不再展开了，欢迎大家在官网文档和实际使用中慢慢发现。

立即上手

如果是 dumi 1.x 的项目，请参考升级文档升级到 dumi 2：d.umijs.org/guide/upgra… 如果是打算新建全新项目，请直接使用 create-dumi 脚手架：d.umijs.org/guide/initi…

后续规划

其实还有很多想做的功能没来得及做，dumi 2.0 发布以后还会继续新增功能，也希望能有更多的社区同学一起参与，这样 dumi 2.1 很快就会到来：

  • 移动端组件研发主题
  • Umi 4 项目集成模式
  • 交互式的 API 表格
  • 组件 Playground
  • Vue 组件渲染支持
  • Monorepo 方案及最佳实践
  • ……

感谢

dumi 2 的发布离不开各位社区开发者的贡献，感谢你们让开源变得美好 ：

Ant Design 5.0 在今天下午进行发布直播，其新官网也是使用 dumi 2.0 搭建的

🎉 dumi 2，它来了它来了它来了