[RFC] dumi 2.0 theme system

[PeachScript]

dumi 1.0 主题方案存在的问题

1. 局部覆盖困难：比如想定制侧边栏就必须覆盖整个 Layout、想自定义 Previewer 的操作栏就必须覆盖整个 Previewer
2. 默认主题覆盖不方便：想局部覆盖默认主题，还必须单独安装 dumi-theme-default
3. 没有开箱即用的国际化方案：只能通过 theme context 拿到 locale 判断、展示文案
4. 缺少全局 Layout：比如想套一层 ConfigProvider，其实需要同时覆写 layouts/index.tsx（用户文档）和 layouts/demo.tsx（用于 Demo 的独立访问页）
5. 缺少工具链：没有主题包研发的脚手架

dumi 2.0 主题方案

目录结构

.
├── builtins         # 全局组件，注册的组件可直接在 Markdown 中使用
├── locales          # 国际化文案，通过 `import { useIntl } from 'dumi'` 来调用文案，自动根据当前的 locale 切换
│   └── zh-CN.json
├── layouts          # 布局组件，会被 dumi 直接引用
│   ├── GlobalLayout # 全局 Layout，通常用来放置 ConfigProvider
│   ├── DocLayout    # 文档 Layout，包含导航、侧边菜单、TOC 等，包裹 Markdown 正文做渲染
│   └── DemoLayout   # 组件示例 Layout，需要控制 demo 独立访问页（`/~demos/:id`）的布局时使用
├── slots            # 局部组件（具体有哪些组件取决于主题包实现，由布局组件从 `dumi/theme/xx` 进行引用，以下为举例）
│   ├── Navbar       # 导航栏
│   ├── NavbarLogo   # 导航栏 LOGO 区域
│   ├── SideMenu     # 侧边栏
│   ├── Homepage     # 首页内容
│   └── HomepageHero # 首页 Hero 区域
└── plugin           # dumi 插件文件，允许主题包参与编译时（还在犹豫）

基于以上结构，解决 1.0 存在的问题：

1. 局部覆盖：通过 slots 下组件的覆盖/包装实现
2. 默认主题覆盖：所有内置主题的组件可从 dumi/theme-default/xx 引入
3. 国际化方案：locales 配合简易版 useIntl（用法类似 @umijs/plugin-locale）
4. 全局 Layout：新增 GlobalLayout

其中,slots、dumi/theme/xx 参考了 Docusaurus 的 Swizzing 设计，slots 的名称及概念借用了 Vue.js 的 slots

主题包的加载逻辑

主题包的优先级从高到低排序：

1. 本地主题：放置在 .dumi/theme 下，与现在一致
2. 安装主题：devDependencies、dependencies 里找到的第一个 dumi-theme- 或 @org/dumi-theme- 的包
3. 内置主题：在 dumi 自己的 NPM 包产物中

其中各个模块的合并方式如下：

1. builtins、layouts、slots 永远是覆盖式加载，开发者可以在覆盖的组件里决定是重写还是包裹原有组件
2. locales 按照单个 locale 文件合并加载，以实现局部覆盖文案的效果

主题相关别名的解析逻辑

一共有 4 个别名：

1. dumi，指向 dumi 提供的主题 API（也包括 umi 的 API），提供 useIntl 之类的便于实现主题包的 API
2. dumi/theme/{layouts,builtins,slots}/xx，指向主题解析的最终结果，包含本地主题，类似 Docusaurus 的 @theme
3. dumi/theme-original/{layouts,builtins,slots}/xx，指向三方主题包及插件修改后的最终结果，不含本地主题，借助 .umi/dumi 的临时文件夹实现，类似 Docusaurus 的 @theme-original
4. dumi/theme-default/xx，指向 dumi 内置的主题包产物，可能就是真实存在的产物目录，类似 Docusaurus 的 @theme-init

工具链

计划提供一个专门的脚手架以及 father + father-plugin-dumi-theme 来提供 dumi 的主题包研发工具链，father 插件主要做以下事情：

1. 定制默认的构建配置 esm: { output: 'dist' }
2. 定制 doctor 规则，比如 layouts 和 builtins 下的组件不允许相对路径直接相互引用、必须从 dumi/theme-slots 引入，以确保未来主题包可被用户局部自定义

暂时想到这些，欢迎提建议及补充 ❤️

[xiaohuoni]

1、有没有一些动态判断的方法，比如说我只要在某个文档的右侧加上广告位，这个要怎么实现？
好像现在的覆盖也能实现，比如 pathname === 'abc' &&<AD />
2、不同的模块用两个主题？比如我主要的 demo 都是 pc 端的，但是我有一个页面需要显示它在移动端上的演示效果？

[PeachScript]

1. 判断还是要自己写的，新版会提供一个 TOC 的 slots，添加更方便一些
2. 这个取决于主题包实现，现在的 mobile 主题包也是支持的，md 头部配 mobile: false

[bojue]

多层级菜单配置可以支持了吗，或者类似docsify提供菜单自定义配置也行 https://docsify.js.org/#/more-pages?id=sidebar

[PeachScript]

默认主题不会支持，为了控制文档解构的复杂度，只提供导航 -> 分组 -> 页面三层关系，未来会再多一层二级导航的关系；但侧边栏是可以自己写 React 组件定制的，useFullSidebarData 可以拿到全量的侧边栏数据，自己按需组装即可

[FanSun521]

useFullSidebarData 拿到数据怎么组装呢 sidebar不支持二级吗 我看只显示一级侧边栏