dtd-site-theme

bisheng-theme-antd

将 ant-design 中相关代码拷贝出来，可以直接在其他项目中使用。

Usage

yarn add bisheng-theme-antd bisheng-plugin-antd bisheng-plugin-react bisheng-plugin-toc -D

配置bisheng.config.js。

const path = require('path');

module.exports = {
    source: {
        components: './components',
        docs: './docs',
    },
    output: './_site',
    theme: 'bisheng-theme-antd',
    themeConfig: {
        siteName: '生态圈',
        logo: 'https://example.com/static/logo.png',
        categoryOrder: {
            'Ant Design': 0,
            原则: 1,
            Principles: 1,
            视觉: 2,
            Visual: 2,
            模式: 3,
            Patterns: 3,
            其他: 6,
            Other: 6,
            Components: 100,
        },
        // 控制左侧菜单
        typeOrder: {
            General: 0,
            Layout: 1,
            Navigation: 2,
            'Data Entry': 3,
            'Data Display': 4,
            Feedback: 5,
            Other: 6,
            通用: 0,
            布局: 1,
            导航: 2,
            数据录入: 3,
            数据展示: 4,
            反馈: 5,
            其他: 6,
        },
    },
    lessConfig: {
        javascriptEnabled: true,
    },
}

对于md文件有一些强制约定需要遵守。

其实更推荐的做法是将bisheng-theme-antd拷贝到本地theme文件夹使用。

目录结构

参考antd的目录，components是读取md文件的根文件夹，在之下直接存放所有公共组件：

components
├── button
│   ├── demo
│   │   └── basic.md
│   └── index.md
├── form
│   └── index.md
└── input
    └── index.md

当访问路径http://127.0.0.1:8000/components/button时，会将components/button解析，以components/button去寻找是否有对应的md文件。

对应代码在bisheng-theme-antd/src/template/Content/index.js中collect部分。

代码示例

组件根文件，即index.md，必须有

---
category: Components
type: 通用
title: Button
subtitle: 按钮
---

category和type是用来控制生成侧边菜单，菜单显示内容为 title + subtitle。

在每个组件文件夹下，如果存在demo文件夹，则会将该文件夹下所有md文件读取，并以Demo组件的形式展示：

每个md文件会生成一个Demo组件，该文件内容有需要符合格式：

---
order: 0
title:
  zh-CN: 按钮类型
  en-US: Type
---

## zh-CN

按钮有四种类型：主按钮、次按钮、虚线按钮、危险按钮。主按钮在同一个操作区域最多出现一次。

## en-US

There are `primary` button, `default` button, `dashed` button and `danger` button in antd.

这里可以放代码块，lang 需要是 jsx

order表示显示的顺序，title会显示在Demo和右侧。正文内容会根据当前语言显示。

一些说明

• 去掉了移动端支持
• 将 components、docs/react、changelog存放md文件的文件夹定义为module

Header

网站顶部，对应组件template/Layout/Header。右侧菜单跳转路径是写死在这个文件内。 「组件」按钮，打开的是docs/react/introduce.zh-CN.md这个文件，所以如果需要「组件」按钮，这个文件必须存在，且内容包含：

---
order: 0
title: Ant Design of React
---

首页

即ant.design的首页，如果作为内部组件库，大部分情况可能都不需要这样一个展示页，所以去掉了。 如果需要增加类似首页，只需要修改Home/index.js即可。

ant.design首页的内容都是写在组件内的，不是通过markdown渲染出来。

文档页

可以放一些项目说明。

Changelog

bisheng 使用记录

source

source支持字符串与对象，如果是字符串，比如./components，并且有如下文件夹：

components
├── button
│   ├── demo
│   │   └── basic.md
│   └── index.md
├── form
│   └── index.md
└── input
    └── index.md

那么生成的markdownData就是：

{
  button: {
    // ...
  },
  form: {
    // ...
  },
  input: {
    // ...
  },
}

如果是对象，配置为：

source: {
  components: './components',
},

同样的文件夹，生成的markdownData变成了：

{
  components: {
    button: {
      // ...
    },
    form: {
      // ...
    },
    input: {
      // ...
    },
  },
}

这个markdownData是在匹配到路由时，用路由去匹配这个数据的，从而获取到md文件内容。

问题

每次修改了md文件需要重启服务。

1、详情页 404

404 就是没有匹配到路由，这个很明显，但是为什么呢？因为theme-one配置的是/posts/:post路径，而我们指定source为其他名字的文件夹，比如

// bisheng.config.s
module.exports = {
    source: './components',
};

那么，在components下的md文件实际访问路径就是/components/:post，所以匹配不到。

2、bisheng-plugin-react 不生效

首先，在lazyload: true的情况下，是使用了src/loader/source-loader.js来处理md文件，使用themeConfig.plugins，所以在这里断点查看实际使用了哪些plugins，并确定路径正确。

大部分不生效可能是因为路径错误。

由于不知道怎么配，所以直接修改node_modules/bisheng-theme-one下的配置文件：

module.exports = {
    // ...
    plugins: [
        path.join(__dirname, '..', '..', 'bisheng-plugin-react?lang=__react'),
    ],
}

bisheng-plugin-react是作用在theme上的，那么只能自己实现theme，而不能使用第三方，因为bisheng.config.js无法覆盖theme.config.js。

在最终使用插件处理前，会使用lib/utils/resolve-plugins.js的resolvePlugins方法去寻找插件路径，并返回有效插件。

function resolvePlugin(plugin) {
    var result;
    try {
        // https://www.npmjs.com/package/resolve
        result = resolve.sync(plugin, {
            basedir: process.cwd()
        });
    } catch (e) {} // eslint-disable-line no-empty
    return result;
}

是以当前执行命令为前提去找，所以在theme中安装的插件是找不到的，需要在项目，也就是这里安装。

如果theme是以依赖的形式安装，那它的依赖应该会放在项目中，就不存在这个问题了？如果只是将项目clone，依赖也不好解决，这又是一个问题。