使用自定义主题

切换主题非常简单, 只需要将根目录文件 config.yml 中的 theme 更改为您想使用的主题即可。

+ theme: custom-theme

如何开发自定义主题包

create-react-doc 脚手架提供了脚本命令 react-doc theme 用来一键创建主题包开发环境。

// 安装 create-react-doc
yarn add create-react-doc -g
// 执行 react-doc theme 并输入主题包名字
react-doc theme

进入到所创建主题目录, 执行 yarn && yarn start, 此时会自动打开浏览器, 并在屏幕中央显示 Write docs happily now.。如下图所示:

恭喜你, 此时你已经将主题开发环境配置完成。接着便可以开始愉快地定制个人主题了。

在所创建的主题项目中使用了 react v18，react-router-dom v6，项目支持使用 less 语法。

import { Switch, Route } from 'react-router-dom'
import styles from './index.less'

const CustomTheme = (props: CustomThemeProps) => {
  return (
    <Routes>
      <Route path="/">
        <div className={styles.center}>Welcome to your own theme</div>
      </Route>
    </Routes>
  )
}

export default CustomTheme

CustomThemeProps 的接口类型暴露了菜单资源 menuSource 与路由资源 routeData, 自定义主题时可以按需使用它们。

interface CustomThemeProps {
  /** 菜单资源 */
  menuSource: {
    /** 文件名称 eg: '快速上手.md' */
    name: string
    /** 文件扩展名 eg: '.md' */
    extension: string
    /** 文件路径 eg: '/docs/快速上手.md' */
    path: string
    /** 路由路径 eg: ‘/快速上手’ */
    routePath: string
    /** 文件大小 eg: 924 */
    size: number
    /** 文件类型 eg: 'file' */
    type: string
    /** 文件创建日期 eg: '2020-11-11' */
    birthtime: string
    /** 文件修改日期 eg: '2021-01-14' */
    mtime: string
  }[]
  /** 路由资源 */
  routeData: {
    /** 文件名称 eg: '快速上手.md' */
    article: string
    /** 异步加载 markdown 组件函数 */
    component: AsyncRouteComponent(props)
    /** markdown 文章信息对象。若为文件则有 title 字段, 若为文件夹则无 title 字段 */
    mdconf: { title?: string }
    /** 文件路径 eg: '/docs/快速上手' */
    path: string
  }[]
}

此外在自定义主题文件中可以自由使用由 webpack 注入的 DOCSCONFIG 对象中的变量, DOCSCONFIG 中的变量与项目根目录中的 config.yml 文件变量一一对应。

比如 config.yml 配置如下所示:

menu: ['Introduction']
theme: crd-seed
user: muyunyun
repo: https://github.com/MuYunyun/create-react-doc
language: en

则主题项目中可以通过如下方式获取到 config.yml 配置属性。

const { menu, theme, user } = DOCSCONFIG || {}