@kylin-design/cli

v0.0.9

Published

3 years ago

适用于kylin-design站点子项目要求的CLI

Downloads

0High
0Medium
0Low

yong.tao

简介

kylin 是将 markdown 文件转换为基于 React 技术栈的站点工具。

用法

安装：

npm i @kylin-design/cli -D

接下来修改 package.json 添加 scripts :

{
  "scripts": {
    "start": "kylin start",
    "build": "kylin build"
  }
}

创建配置文件 kylin.config.js:

module.exports = {
  port: 4000,
  basename: 'kylin',
  name: 'kylin.Design',
  source: './docs',
  output: './_site',
};

**注释：**请确保 source 目录存在。

命令行

Usage: kylin [command] [options]

Options:
  -V, --version    output the version number
  -h, --help       display help for command

Commands:
  start [options]  启动一个开发服务
  build [options]  在目录 `config.output` 中生成相关编译代码
  help [command]   display help for command

约定式路由

其实就是不需要手写配置，文件系统即路由，通过目录与文及其命名分析出路由配置。

比如：

─ docs
   ├── components
   │    ├── affix
   │    │    └─ index.md
   │    ├── anchor
   │    │    └─ index.md
   └── CHANGELOG.md

会得到以下路由配置

[
  {
    path: 'docs/components/affix/index.md',
    link: 'docs/components/affix',
    groups: [],
    name: 'affix',
  },
  {
    path: 'docs/components/anchor/index.md',
    link: 'docs/components/select',
    groups: [],
    name: 'anchor',
  },
];

需要注意的是，满足一下任意负责的文件不会被注册为路由：

非.md类型文件

配置

kylin 在启动时会自动读取配置文件 kylin.config.js，获取是使用 --config 指定配置文件路径。比如： kylin start --config design.config.js

kylin.config.js 配置文件内容如下：

module.exports = {
  port: 40000,
  name: 'kylin.Design',
  source: './posts',
  output: './_site',
  basename: 'kylin-ui',
  webpackConfig: config => {
    config.output.library = 'kylin_design';
    config.output.libraryTarget = 'umd';
    config.output.jsonpFunction = 'webpackJsonp_kylin_design';
    config.output.globalObject = 'window';
    config.output.publicPath = '/';

    return config;
  },
  devServerConfig: {
    historyApiFallback: true,
    headers: { 'Access-Control-Allow-Origin': '*' },
  },
  branchUrl: 'http://gitlab.shuyun.com',
};

port

Type: number
Default: 4000

配置本地服务监听的端口号

name

Type: string
Default: 'kylin.Design'

站点名称

source

Type: string | Record<string, string>
Default: './posts'

设置 markdown 文件的目录，即路由扫描目录

output

Type: string
Default: './\_site'

设置生成文件目录（js、css、html）

basename

Type: string
Default : '/'

设置路由基本路由。格式要求不能以斜杠开头，也不能以斜杠结尾。

注释： basename 会被用于生成 html 页面时样式前缀。如 basename: 'ui' 那么此时 h2 被编译为 toc 后会追加样式 ui-toc-h2

themeConfig

Type: object
default: undefined

设置页面中优先级；

如：

{
  themeConfig: {
    categoryOrder: {
      components: 100,
      docs: 99
    },
    typeOrder: {
      导航: 2,
      反馈: 1
    },
  }
}

pick

-Type: (filepath:string) => { groups: string | string[] }; -Default: {} 设置路由分组

比如：

 pick: {
    component(filepath) {
      if (/^posts\/components\//.test(filepath)) {
        const index = filepath === 'posts/components/affix/index.md';

        return { groups: ['components'] };
      }

      return null;
    },
    docs(filepath) {
      if (/^posts\/docs\//.test(filepath)) {
        return { groups: ['components', 'docs'] };
      }

      return null;
    },
  },

生成路由配置：

[
  {
    "path": "posts/components/affix/index.md",
    "link": "components/affix",
    "groups": [["components"]],
    "name": "ComponentsAffix"
  },
  {
    "path": "posts/docs/getting-started.zh-CN.md",
    "link": "docs/getting-started",
    "groups": [["components", "docs"]],
    "name": "DocsGettingStarted"
  },
  {
    "path": "posts/components/affix/index.md",
    "link": "components/affix",
    "from": "components"
  }
]

webpackConfig

-Type: (defaultConf, webpack)=> webpackConfig;

设置自定义 webpack 配置

devServerConfig

设置开发服务器环境

branchUrl

-Type: string 设置代码仓库地址，便于用户编辑，注意此路径不能以 / 结尾。

appendMenus

-Type: Array<{ category?: string; type?: string; order: number; title: string; subtitle?: string; target?: '_blank' | '_self'; }>

附加菜单比如：

若在现有菜单的基础上追加一个跳转至 https://www.XXX.com的菜单，我们可以这样配置

appendMenus: [
    {
      order: 10,
      title: '跳转至XXX',
      target: '_blank',
      link: 'https://www.xxx.com',
    },
  ],

appendRoutes

-Type : {type: 'Route', path: string, component?: '404'} | {type: 'Redirect', from: string, to: string}

附加路由，在约定式路由的基础之上添加自定已路由，比如：

 appendRoutes: [
    {
      type: 'Route',
      path: 'component/*',
      component: '404',
    },
    {
      type: 'Redirect',
      from: 'component',
      to: 'component/affix',
    },

上面的配置在运行时会被替换为 React-router 的组件 Route 与 Redirect,

<Route key="./errors/not-found" path="/component/*" component={NotFoundPage} />
<Redirect key="component" to="/component/affix" from="/component" />

demoPresetDependencies

-Type: Record<string, string>

Demo 代码中预设的依赖版本信息。

举例：

import React from 'react';
import { ProInput } from '@kylin-design/pro';

export default () => {
  return <ProInput />;
};

这段代码中解析器只会得到依赖 ['@kylin-design/pro', 'react'],但是 @kylin-design/pro 运行有需要依赖 @shuyun-ep-team/kylin-ui。中场景下就需要使用 demoPresetDependencies 配置了。它会将这其中的依赖以及版本信息添加到依赖列表中。

demoIgnoreDependencies

-Type: Array<string| { name:string, version:string }>

Demo 代码中需要忽略的依赖版本信息。

若 demoIgnoreDependencies 中元素是 string 则忽略依赖以后生成的依赖列表中被忽略的依赖包版本被设置为 latest ;

npmClient

-Type 'npm' | 'yarn' -default 'npm'

兼容依赖版本时可能需要安装 hack 依赖

markdown 文件规范

页头 meta 数据配置

设置页面 title 以及页面类型等信息，一下是全量文案配置：

---
category: Components
type: 导航
order: 1
title: 图钉
subtitle: Affix
---

category: 类型名称
type: 二级分类
title: 标题
subtitle: 二级标题
order: 排序（排序为降序）

关于类型排序以及二级分类的排序是在配置文件的 config.themeConfig 中配置配置，分别为 categoryOrder、typeOrder,例如：

themeConfig: {
    categoryOrder: {
      Components: 100,
      Docs: 90
    },
    typeOrder: {
      导航: 2,
    },
  },

上面的数据会被转义为左侧菜单栏数据，其结构为：

   ├── Components
   │    └── 导航
   │         ├── affix
   │         └── anchor
   │    
   └── Docs
        └─ getting-started

demos

设置 demo 使用的匹配规则是 h4 + hr + demo 即：

#### 按钮类型

---

按钮类型分为....

<demo src="./demo/basic.tsx" cols="12" />

通过上面的格式配置，kylin 会将其解析为 demos 配置：

{
  title: any[];
  content: any[];
  attributes: { src: string; cols?: number };
  code?: string;
  highlight?: any[];
}

title: 名称标题
content: demo 简单描述
attributes: 为 demo 配置，其中 src 为 demo 文件的路径，用于代码引入；cols 为 demo 代码块布局比例，此处使用的为栅格布局配置，其建议设置 12 或 24，若不设置则默认为 24
code: 源码
highlight: 高亮源码
dependencies: 源码中 import 导入的模块名称，供在线运行沙盒使用。

注意： 此配置一定要注意简单描述与标签 <demo src="..." /> 之间有一空行。