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

2021年09月19日 18:48

业务组件文档

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