从 father-doc 迁移

注意,此处的 father-doc 并非原有 father 工具集中的 father doc 部分,本手册仅适用于 father-doc 的迁移

father-doc 是 dumi 的前身,在 2019 年 10 月 23 日发出了第一个 alpha 版本,感谢曾经使用和贡献 father-doc 的伙伴们,如今 father-doc 已正式更名为 dumi,且做了很多不兼容的变更,真诚邀请大家进行迁移,只需要 3 分钟即可快速搞定。

配置项变更

所有配置项都从原有的 config.doc 层级提升到了 config 层级,即全部到最外层了,部分配置项也做了更名,详细变化如下:

变更对照表

新配置项名称原配置项名称作用
titledoc.title设置网站的标题,默认值为 package.name
descriptiondoc.desc设置网站的介绍文字,目前仅 doc 模式下有用
logodoc.logo设置网站的 LOGO
modedoc.mode设置网站的类型
localesdoc.locales设置网站的多语言配置
menusdoc.menus配置网站的侧边栏菜单
navsdoc.navs配置网站的导航菜单
resolve.includesdoc.include设置文档的探测目录
resolve.previewLangsdoc.previewLangs设置哪些代码块语言会被当做 React Component 渲染

API 改名

需要注意的是,上述有两个 API 除了提升层级外,还做了改名,分别是:

  • desc 修改为 description:不用缩写
  • include 修改为 includes:修正单复数

FrontMatter 变更

对于 Markdown 文件的 FrontMatter 配置,dumi 也做了修改,详细情况如下:

order 的排序规则反向

order 的排序规则由越大越靠前修改为越小越靠前

一开始路由、菜单和导航的 order 规则都是 order 值越大越靠前,但大家实际使用下来很不方便,随着页面的增多经常需要把第一篇文档的 order 值再改大一些,所以做了反序。

废弃 slugs 改用 toc

此前 father-doc 用 slugs: false 来关闭右侧的锚点菜单展示,在 dumi 中,改用 toc 配置项来控制,且存在 3 种值:false 关闭、menu 集成到右侧菜单、content 展示在内容区域(默认值)。

修正语义,我们这个场景确实是 sidemenu

hero.text 改为 hero.title

修正语义,首页 HERO 区域应为 title

其他杂项

gitignore

由于 Umi 3 的临时文件目录从 pages 文件夹提升到了根目录,所以如果原有 gitignore 中存在 pages/.umi,需要修改为 .umi