dumi 和 Umi 的关系是什么?

dumi 本体是一个 Umi 的 preset——@umijs/preset-dumi,也就是说,我们可以在一个 Umi 的项目中同时使用 dumi。但为了避免 Umi 项目的配置项与 dumi 文档的配置项冲突,建议使用 UMI_ENV 进行区分。

配置项只有这些吗?想实现更多的功能怎么办?

dumi 基于 Umi,即除了自己提供的配置项以外,还支持所有 Umi 的配置项,并且也支持 Umi 生态的插件,所以如果需要更多的功能,可以先看一下 Umi 的配置项和插件生态能否满足,如果仍旧不能,欢迎到讨论群反馈或者 GitHub 上提出 Feature Request

为什么 README.md 会出现在文档的首页?

无论是文档还是官网,一定会有首页。dumi 会优先在所有的 resolve.includes 文件夹下寻找 index.md 或者 README.md,如果找不到的话则会使用项目根目录的 README.md

如何完全自定义首页?

目前 dumi 尚未开放主题自定义功能,可以通过引入外部嵌入式 Demo 的形式来实现:

<!-- index.md -->
<code src="path/to/homepage.tsx" inline />

详细使用可参考 Ant Design Landing 的 use in dumi

如何自定义“编辑此页”?

当您在根目录的 package.json 中设置 repository 后,dumi 就会在页面底部生成相应的编辑功能按钮。例如:

// package.json
{
"repository": {
"type": "git",
"url": "git+https://github.com/umijs/dumi.git",
"branch": "master",
"platform": "github"
}
}

其中:

  • url:决定跳转仓库仓库路径
  • branch:对应仓库分支。默认为 master
  • platform:对应平台。当前设置为 gitlab 时,若 url 涉及 subgroups 会对其进行特殊处理

dumi 支持使用 .md 之外的其他方式编写文档吗?

暂不支持。

如何在 cra 等非 umi 项目中使用 dumi?

源码示例

  1. 安装模块。
yarn add dumi cross-env -D
  1. 增加启动命令,修改 package.json
"scripts": {
"dumi": "cross-env APP_ROOT=dumi dumi dev",
"dumi-build": "cross-env APP_ROOT=dumi dumi build"
},
  1. 增加配置,新建 dumi/config/config.js
export default {
chainWebpack(memo) {
memo.plugins.delete('copy');
},
};
  1. 新建文档目录 dumi/docs/,这里的 dumi 目录即第二步中配置的环境变量,你可以随意同步修改。

  2. 新建文档 dumi/docs/index.md

# 这是一个 Dumi 结合 create-react-app 的 Demo
  1. 将 dumi 的临时文件添加到 .gitignore 中。
.umi

dumi 支持基于其他技术框架、例如 Vue、Angular 编写文档和 Demo 吗?

暂不支持;但 Umi 3 在架构上对 renderer 做了抽离,后续如果有其他的 renderer,dumi 也会进行跟进。

如何添加统计脚本和全局 CSS 样式?

可使用 Umi 的 stylesscripts 配置项。

本地开发没问题,但部署完成后访问子页面再刷新就 404 了

默认只输出一个 index.html 作为入口 HTML 文件,服务器在 serve / 时可以找到文件但 /some-route 却没有对应的 /some-route/index.html,所以会出现 404。设置 config.exportStatic{} 根据路由按文件夹结构输出所有 HTML 文件即可,此配置项的更多用法可参考 Umi 文档:Config - exportStatic

文档构建后的 bundle 太大了,导致网站访问速度很慢,如何实现按需加载?

配置 config.dynamicImport{},此配置项的更多用法可参考 Umi 文档:Config - dynamicImport

部署文档

非根目录部署

非根目录部署需要修改 Umi 的 base 配置项视实际情况 修改 publicPath 配置项

export default {
base: '/文档起始路由',
publicPath: '/静态资源起始路径/',
exportStatic: {}, // 将所有路由输出为 HTML 目录结构,以免刷新页面时 404
// 其他配置
};

文档项目独立时, 通常 basepublicPath 配置项相同。

部署到GitHub Pages

由于 GitHub Pages 是非域名根路径部署, basepublicPath 配置项需改为 仓库名称 。参考 非根目录部署

手动部署

借助 gh-pages 可以轻松帮助我们部署文档到 Github Page

npm install gh-pages --save-dev

or

yarn add gh-pages -D

package.json 中添加

"scripts": {
"deploy": "gh-pages -d dist"
}

编译生成 dist 目录

npm run docs:build

一键发布

npm run deploy

自动部署

利用 Github Action 在每次 master 分支更新后自动部署

新建 .github/workflows/gh-pages.yml 文件

name: github pages
on:
push:
branches:
- master # default branch
jobs:
deploy:
runs-on: ubuntu-18.04
steps:
- uses: actions/checkout@v2
- run: npm install
- run: npm run docs:build
- name: Deploy
uses: peaceiris/actions-gh-pages@v3
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ./docs-dist

开发阶段,如何配置 md 文件中的样式按需引入?

dumi 会对 pkgName/es、pkgName/lib 做 alias,详情见

配置 extraBabelPlugins (注意是 .umirc.ts 的配置项,不是 .fatherrc.ts),加入 babel-plugin-import,根据目录结构合理配置

例如:

目录结构:

├── scripts
│   └── hack-depend.js
├── src
│   ├── Button
│   │   ├── style
│   │   │   ├── index.less
│   │   │   └── mixin.less
│   │   ├── index.md
│   │   └── index.tsx
│   ├── style
│   │   ├── base.less
│   │   ├── color.less
│   │   └── mixin.less
│   └── index.ts
├── .editorconfig
├── .fatherrc.ts
├── .gitignore
├── .prettierignore
├── .prettierrc
├── .umirc.ts
├── README.md
├── package.json
├── tsconfig.json
├── typings.d.ts
└── yarn.lock

配置 .umirc.ts:

extraBabelPlugins: [
[
'import',
{
libraryName: 'lean',
camel2DashComponentName: false,
customStyleName: name => {
return `./style/index.less`; // 注意:这里 ./ 不可省略
},
},
'lean',
],
];

在 md 中引入组件:

import { Button } from 'lean'; // 这里会按需引入样式

dumi 如何支持对 Swift、C#、Kotlin 等语言的语法高亮?

dumi 语法高亮使用的 prism-react-renderer ,是一款基于 PrismJS 实现的 React 组件。 PrismJS 支持的语言种类很多,但 prism-react-renderer 在实现的时候对部分语言进行了移除,其具体原因可以查看 Adding Out of the Box Languages

我们在 dumi 中可以通过下面的方式,添加对其他语言的支持:

// src/app.ts
import Prism from 'prism-react-renderer/prism';
(typeof global !== 'undefined' ? global : window).Prism = Prism;
require('prismjs/components/prism-kotlin');
require('prismjs/components/prism-csharp');

非 umi 项目启动 dumi 后提示 Error: register failed, invalid key xx from plugin src/app.ts

由于 src/app.(t|j)sx? 是 dumi 运行时配置文件的约定,请避开此路径创建文件;如果无法避开命名,可参考上方[修改 APP_ROOT](#如何在 cra 等非 umi 项目中使用 dumi?) 的方式切换 dumi 的运行目录实现规避。