前言

dumi 是一款为组件开发场景而生的静态站点框架，与 father 一起为开发者提供一站式的组件开发体验，father 负责组件源码构建，而 dumi 负责组件开发及组件文档生成。

本文是基础篇，适合第一次接触dumi的读者，本文为 pnpm+monorepo+changesets+dumi 构建React组件库 文章的基础补充

dumi

1. 约定式路由

1. 文档路由

默认在docs目录，仅识别 .md 后缀的文件，识别路径可通过 resolve.docDirs 进行修改；

2. 资产路由（包路由）

默认在src目录，仅识别第一层级的 .md 文件及第二层级的 index.md、README.md 文件。可通过 resolve.atomDirs 进行修改

3. React路由

默认在.dumi/pages目录，适用于为当前站点添加额外的、无法用 Markdown 编写的复杂页面。

2. 菜单生成

顶部的菜单（一级菜单）可通过.dumirc.ts的nav配置项实现，约定更方便

页面的菜单栏，需手动在index.md文档开头声明

---
title: Background 背景图片
toc: content
group:
  title: 通用
  order: 0
---

title：二级菜单栏名称

toc：为content，三级菜单栏显示在内容区域右侧；为false，不根据内存生成三级菜单

group：分类。title为分类的名称，order为排序的顺序。

3. demo分栏配置

对demo项目进行分栏

---
demo:
  cols: 2
---

<!-- 其他 Markdown 内容 -->

配置 demo.cols 后,以下多个 demo 完将会被渲染为双栏布局：

<code src="./demos/cols.tsx">分栏 1</code>
<code src="./demos/cols.tsx">分栏 2</code>
<code src="./demos/cols.tsx">分栏 3</code>
<code src="./demos/cols.tsx">分栏 4</code>

4. 写组件demo

1. 代码块

2. 外部demo

如果我们的 demo 非常复杂，甚至可能有很多外部文件，那么建议使用外部 demo：

<code src="/path/to/complex-demo.tsx"></code>

3. 引入组件

假设我们正在研发的组件库 NPM 包名叫做 @wjcao/components，我们正在为其中的 Button 组件编写 demo

import { Button } from '@wjcao/components';

5. 控制 demo 渲染

dumi 提供了一些 FrontMatter 属性，以满足不同的 demo 渲染需求，在源代码顶部配置即可：

对于外部 demo，这些 FrontMatter 属性除了写在源代码里，也可以写在 code 标签的属性上：

<code src="/path/to/demo" 配置项="值"></code>

（1）捕获fixed元素

设置 transform 为 true，可使得内部 position: fixed; 元素相对于 Demo 包裹器定位：

/**
 * transform: true
 */


import React from 'react';

export default () => <h1 style={{ position: 'fixed', top: 0, left: 0 }}>我不会飞出去</h1>;

（2）标题与简介

/**
 * title: 我是标题
 * description: 我是简介，我可以用 `Markdown` 来编写
 */

import React from 'react';

export default () => null;

（3）iframe模式

设置 iframe 为 true，将会使用 iframe 渲染 demo，可实现和文档的完全隔离，通常用于布局型组件：

/**
 * iframe: true // 设置为数值可控制 iframe 高度
 */
import React from 'react';

export default () => (
  <h2 style={{ boxShadow: '0 2px 15px rgba(0,0,0,0.1)', padding: '5px 20px' }}>iframe 模式</h2>
);

6. 使用内置组件

dumi 提供了一系列内置组件作为 Markdown 语法的补充，除了上面我们已经用到过的 code 以外，还支持这些：

1. Alert

使用 Alert 创建一个提示框，type 可选 warning、info、success、error，默认为 info。

<Alert type="info">
  注意，内部暂时只能编写 HTML
</Alert>

2. Badge

使用 Badge 可以创建一个标签：

#### 标签测试 <Badge>Hello</Badge>

Markdowm基本语法

1. 标题

标题用#表示，一个#是一级标题，两个#是二级标题

# 这是一级标题
## 这是二级标题
### 这是三级标题
#### 这是四级标题
##### 这是五级标题
###### 这是六级标题

2. 字体

斜体：用一个*包裹

加粗：用两个*包裹

斜体加粗：用三个*包裹

删除线：用两个~包裹

*这是倾斜的文字*
**这是加粗的文字**
***这是斜体加粗的文字***
~~这是加删除线的文字~~

3. 分割线

三个或三个以上的-或者*都可以

---
----
***
*****

4. 图片

![图片alt](图片地址 ''图片title'')

图片alt就是显示在图片下面的文字，相当于对图片内容的解释。

图片title是图片的标题，当鼠标移到图片上时显示的内容。title可加可不加

示例：

![二维码](https://wen.caowj.top/wx.jpg "公众号")

5. 超链接

[超链接名](超链接地址 "超链接title") 

title可加可不加

示例：

6. 列表

1. 无序列表

用 - + * 任何一种都可以

- 列表内容
+ 列表内容
* 列表内容

注意：- + * 跟内容之间都要有一个空格

2. 有序列表

数字加点

1. 列表内容
2. 列表内容
3. 列表内容

注意：序号跟内容之间要有空格

3. 列表嵌套

上一级和下一级之间敲三个空格

7. 表格

表头|表头|表头
---|:--:|---:
内容|内容|内容
内容|内容|内容

第二行分割表头和内容。

- 有一个就行，为了对齐，多加了几个

文字默认居左

- 两边加：表示文字居中

- 右边加：表示文字居右

注：原生的语法两边都要用 | 包起来。此处省略

8. 代码

1. 单行代码

一个反引号包裹

`代码内容`

1. 多行代码

三个反引号包裹，且反引号单独占一行

9. 引用

> 这是个引用