使用 vuePress 搭建自己的组件库文档

3,791 阅读2分钟

业务组件文档

使用 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

image.png

添加组件,使之可交互,以便查看组件效果 详情参照 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 的错误,如下: image.png

可能是安装依赖时错误,重新安装 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

image.png

block.vue

准备好一切, 重新 npm run dev 能正常启动项目了。由于想做成 element-ui 的组件文档类似的效果

上面是显示组件, 中间是组件说明, 下面是 demo 代码三部分,我额外写了一个 vue 组件 block.vue , 该组件中有3个插槽对应这三部分。

image.png

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 中插槽写法,详细见文档

后面继续充实自己的业务组件