业务组件文档
使用 vuepress 搭建
mkdir docs // 创建一个项目目录
npm init -y // 初始化 npm 环境
npm i vuepress // 安装依赖
npm element-ui highlight.js
npm i less less-loader -D
复制代码
highlight.js 是为了代码高亮的。
入口文件
vuepress 项目的入口文件
doc/README.md
README.md, 文件名必须是大写,不然识别不了
配置文件
根目录下创建 .vuepress 文件夹,然后在该目录下创建 config.js 文件, 设置导航栏和侧边栏。更多配置查看官网
module.exports = {
title: '业务组件库',
description: '常用的业务组件',
dest: './build',
port: 1234,
themeConfig: {
nav: [
{
text: '主页',
link: '/'
},
],
sidebar: {
'/components/': [{
collapsable: true,
children: [
'card'
]
}]
}
}
}
复制代码
修改默认样式 详细类名说明查看官网
创建.vuepress/style/palette.styl 文件
// 颜色
$codeBgColor = #fafafa // 代码背景颜色
$accentColor = #3eaf7c
$textColor = #2c3e50
$borderColor = #eaecef
$arrowBgColor = #ccc
$badgeTipColor = #42b983
$badgeWarningColor = darken(#ffe564, 35%)
$badgeErrorColor = #DA5961
.content pre {
margin: 0!important;
}
.theme-default-content:not(.custom) {
max-width: 1000px !important;
}
复制代码
创建文档文件
在项目根目录下创建 components 文件夹, 该文件夹下创建 md 文件。
components/card.md
添加组件,使之可交互,以便查看组件效果 详情参照 md 中使用 vue 组件
所有在 .vuepress/components
中找到的 *.vue
文件将会自动地被注册为全局的异步组件,如:
.
└─ .vuepress
└─ components
├─ demo-1.vue
├─ OtherComponent.vue
└─ Foo
└─ Bar.vue
复制代码
core-js not found
你可以直接使用这些组件在任意的 Markdown 文件中(组件名是通过文件名取到的)
<demo-1/>
<OtherComponent/>
<Foo-Bar/>
复制代码
引入完组件后, 你可能会遇到 code-js not found 的错误,如下:
可能是安装依赖时错误,重新安装 code-js 就可以了。如果重新安装完还是不行,可以删除 node-modules , 重新安装后正常了。
less: this.getOptions is not a function
我的组件用的 less 语法,vuepress 中已经内置了 less 的配置,只需安装一下依赖就行了
npm i less less-loader -D
复制代码
安装完之后,你可能会遇到 this.getOptions is not a function 的错误提示,后来发现是 less-loader 版本过高,最新版本中没有 getOptions 方法。通过安装指定版本解决
npm i less-loader@5.0.0 -D
复制代码
block.vue
准备好一切, 重新 npm run dev 能正常启动项目了。由于想做成 element-ui 的组件文档类似的效果
上面是显示组件, 中间是组件说明, 下面是 demo 代码三部分,我额外写了一个 vue 组件 block.vue , 该组件中有3个插槽对应这三部分。
bloack.vue
<template>
<div class="block">
<div >
<slot name='source'></slot>
</div>
<div >
<div class="description"
v-if='$slots.default'>
<slot></slot>
</div>
<div class="highlight"
v-highlight>
<slot name='highlight'></slot>
</div>
</div>
<div
@click='isExpanded = !isExpanded'>
<transition name='arrow-list'>
<i :class='[iconClass, {hovering: hovering}]'></i>
</transition>
<transition >
<span v-show="hovering">{{controlText}}</span>
</transition>
</div>
</div>
</template>
复制代码
v-highlight
指令是为了高亮代码块的
import hljs from "highlight.js";
import 'highlight.js/styles/googlecode.css'
Vue.directive('highlight', function(el) {
const blocks = el.querySelectorAll('pre code')
blocks.forEach(block => {
hljs.highlightBlock(block)
})
})
复制代码
markdown 插槽
准备好这一切,我们的组件文档可以这样写
### 银行卡信息收集组件
<block>
:::slot source
<Card />
:::
这是卡信息收集组件
:::slot highlight
`` vue
<template>
<Card />
</template>
``
:::
</block>
复制代码
这里的三个冒号是 markdown 中插槽写法,详细见文档