从 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
层级,即全部到最外层了,部分配置项也做了更名,详细变化如下:
变更对照表
新配置项名称 | 原配置项名称 | 作用 |
---|---|---|
title | doc.title | 设置网站的标题,默认值为 package.name |
description | doc.desc | 设置网站的介绍文字,目前仅 doc 模式下有用 |
logo | doc.logo | 设置网站的 LOGO |
mode | doc.mode | 设置网站的类型 |
locales | doc.locales | 设置网站的多语言配置 |
menus | doc.menus | 配置网站的侧边栏菜单 |
navs | doc.navs | 配置网站的导航菜单 |
resolve.includes | doc.include | 设置文档的探测目录 |
resolve.previewLangs | doc.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
展示在内容区域(默认值)。
sidebar
改为 sidemenu
修正语义,我们这个场景确实是 sidemenu
。
hero.text
改为 hero.title
修正语义,首页 HERO 区域应为 title
。
其他杂项
gitignore
由于 Umi 3 的临时文件目录从 pages
文件夹提升到了根目录,所以如果原有 gitignore
中存在 pages/.umi
,需要修改为 .umi
。