FrontMatter

FrontMatter 是指文件最顶部对正文进行配置的部分,在 dumi 中,FrontMatter 均以 YAML 语法进行编写;除了 Markdown 文件,dumi 也支持在 demo 中配置用于 demo 展示的 FrontMatter,来看两个范例:

在 Markdown 文件中编写 FrontMatter:

---
title: 标题内容
---

在 demo 中编写 FrontMatter:

/**
* title: 标题内容
*/

无论是代码块的形式还是外部 demo,均支持 FrontMatter,外部 demo 不仅支持在源代码中进行配置,也可以给 code 标签添加属性进行配置,比如:

<code src="/path/to/demo.tsx" title="这样也可以配置 demo 标题"></code>

Markdown 配置项

title

  • 类型:String
  • 默认值:正文第一个标题
  • 详细:

用于配置该页面的标题,将会被用作该页面标题的子标题以及左侧菜单。

sidemenu

  • 类型:Boolean
  • 默认值:true
  • 详细:

控制侧边栏菜单的显示或隐藏。

toc

  • 类型:false | 'content' | 'menu'
  • 默认值:'content'
  • 详细:

控制锚点目录的显示或位置,值为 false 时不展示,值为 content 时展示在内容区域的右侧(Affix Menu),值为 menu 时会将当前路由的锚点目录展示在左侧菜单中。

order

  • 类型:Number
  • 默认值:null
  • 详细:

控制该文档的显示顺序,数值越小排序越靠前。

legacy

  • 类型:String
  • 默认值:null
  • 详细:

指定该文档的旧路径(从根路径开始指定),避免从其他文档迁移到 dumi 后原路径访问 404

group

  • 类型:Object
  • 默认值:null
  • 详细:

该配置用于对当前页面进行分组,这样可以在侧边栏菜单进行分组显示,我们可以通过下方三项 FrontMatter 配置项显示地对 group 进行配置,也可以基于 dumi 的文件夹嵌套来自动生成 group,例如:

.
└── src/
├── components/
├── index.md
├── a.md
├── b.md

dumi 会自动为 index.mda.mdb.md 指定 group.titleComponentsgroup.path/components。并且我们可以通过 FrontMatter 对生成的默认配置进行选择性复写,比如:

---
group:
title: 组件
---

则最终生成的 group.path 还是 /components,但 group.title 则变成了 组件

group.title

  • 类型:String
  • 详细:

用于配置侧边栏菜单中该组别的菜单项名称,如果未配置则会默认读取 group.path 并转换为 title,例如将 /components 转换为 Components

group.path

  • 类型:String
  • 详细:

必选,配置该组别的路由前缀,当 location.pathname 匹配到该前缀时,菜单组会进行 active 标记。

group.order

  • 类型:Number
  • 默认值:null
  • 详细:

控制该文档组的显示顺序,数值越小排序越靠前。

  • 类型:Object
  • 默认值:null
  • 详细:

仅 site 模式下可用,该配置用于手动指定当前文档所处的导航菜单,默认根据第一级路由路径自动生成,子配置项与 group 一致。

略,与 group.title 一致。

略,与 group.path 一致。

略,与 group.order 一致。

hero

  • 类型:Object
  • 默认值:null
  • 详细:

在 site 模式下可用,配置 hero 后,该页面将会以首页形式呈现。

hero.image

  • 类型:String
  • 默认值:null
  • 详细:

配置首页首屏区域的标题配图。

hero.title

  • 类型:String
  • 默认值:null
  • 详细:

配置首页首屏区域的大标题。

hero.desc

  • 类型:String
  • 默认值:null
  • 详细:

配置首页首屏区域的简介文字。

hero.actions

  • 类型:Array
  • 默认值:null
  • 详细:

配置首页首屏区域的操作按钮,最后一个按钮会作为主按钮展示,配置格式如下:

hero:
actions:
- text: Getting Started
link: /getting-started

features

  • 类型:Object
  • 默认值:null
  • 详细:

在 site 模式下可用,配置后该页面将会以首页形式呈现,用于每行 3 个的形式展示组件库的特性,配置格式如下:

features:
- icon: 图标的 URL 地址,建议切图尺寸为 144 * 144(可选)
title: 性能强大
link: 可为标题配置超链接
desc: 可以配置 `markdown` 文本
  • 类型:Markdown
  • 默认值:null
  • 详细:

配置当前页面的 footer 区域,建议首页做配置即可,目前暂不支持统一对所有页面进行配置。

translateHelp

  • 类型:Boolean | String
  • 默认值:false
  • 详细:

是否在该页面顶部展示『帮助翻译』的提示框。当设置 String 类型时,会自定义提示语内容。

hide 1.1.0+

  • 类型:Boolean
  • 默认值:false
  • 详细:

如果你暂时不希望在生产环境的站点中展示某些文档,可以打开这个配置临时隐藏它,该配置不会影响开发环境的渲染。

demo 配置项

title

  • 类型:String
  • 默认值:null
  • 详细:

用于配置该外部 Demo 的标题,配置后会在 Demo 预览器中显示。

desc

  • 类型:Markdown
  • 默认值:null
  • 详细:

用于配置该外部 Demo 的简介,配置后会在 Demo 预览器中显示,支持 Markdown 语法。

compact

  • 类型:Boolean
  • 默认值:false
  • 详细:

用于去除 demo 渲染容器的内边距。

background

  • 类型:CSSPropertyValue
  • 默认值:null
  • 详细:

用于设置 demo 渲染容器的背景色。

inline

  • 类型:Boolean
  • 默认值:false
  • 详细:

用于指示该 demo 为自由 demo,将会直接在文档中嵌入渲染,不会被 demo 容器包裹,用户也无法查看源代码。

transform

  • 类型:Boolean
  • 默认值:false
  • 详细:

用于控制 demo 的包裹容器是否设置 transform 的 CSS 值以控制 position: fixed; 的元素相对于 demo 容器定位。

defaultShowCode

  • 类型:Boolean
  • 默认值:false
  • 详细:

用于控制当前 demo 的包裹容器是否默认展开源代码显示。

debug 1.1.0+

  • 类型:Boolean
  • 默认值:false
  • 详细:

标记当前 demo 为调试 demo,这意味着在生产模式下该 demo 是不可见的;另外,调试 demo 在开发环境下也会展示一个 DEV ONLY 的标记,以便开发者将其和其他 demo 区分开来。

hideActions

  • 类型:Array<'CSB' | 'EXTERNAL'>
  • 默认值:[]
  • 详细:

用于控制 Demo 预览器部分功能按钮的隐藏,配置值含义如下:

  • CSB: 隐藏『在 codesandbox.io 中打开』的按钮
  • EXTERNAL: 隐藏『在新窗口打开』的按钮

通过 code 标签的属性配置:

<!-- 注意,单引号为必备,要确保值为有效 JSON 字符串 -->
<code hideActions='["CSB"]' />

通过 frontmatter 配置:

/**
* hideActions: ["CSB"]
* hideActions:
* - CSB
*/
// 以上两种方式均可识别

iframe 1.1.0+

  • 类型:Boolean | Number
  • 默认值:false
  • 详细:

使用 iframe 模式渲染当前 demo,对于渲染 layout 型的 demo 非常有用,当我们传递数值时可以控制 iframe 的高度,访问 iframe 模式 了解更多。

demoUrl 1.1.1+

  • 类型:String
  • 默认值:dumi 自动生成的 demo 独立访问链接
  • 详细:

用于指定该 demo 的访问链接,通常在 dumi 默认渲染的 demo 无法满足展示需要时使用,例如需要呈现 ReactNative 的渲染结果。

在默认主题时,仅在 iframe 呈现模式下才会生效;在移动端研发主题中,会作为右侧手机预览框中的 demo 渲染链接。