VuePress2 搭建组件库文档

前言

在开发自有组件库时，需要有一个组件说明文档，以及组件使用示例。记录从开发到部署以及遇到的问题...

VuePress 安装

VuePress 传送门 选用VuePress主要是因为它的默认样式和Vue官方文档风格几乎一致。

1.安装依赖（因为用了vuepress-plugin-demoblock-plus 所以对安装依赖和版本有要求，可以看下文档说明）

npm i -D @vuepress/client@2.0.0-beta.51 vuepress@2.0.0-beta.51

2.在 package.json 中增加 scripts，用于启动项目和打包

{
  "scripts": {
    "docs:dev": "vuepress dev docs",
    "docs:build": "vuepress build docs"
  }
}

3.创建一个 README.md 文件 4.启动项目

npm run docs:dev

5.启动后页面显示

目录结构

目录结构如下：

配置文件

如果没有配置文件，VuePress 站点只会有一些基础的功能，为了更好的自定义你的组件库文档，需要在 .vuepress 目录下，创建 config.js 或 config.ts 文件。 这个是我的配置文件，包含了导航和侧边栏的一些配置：

import { defineUserConfig, defaultTheme } from 'vuepress'

export default defineUserConfig({
  lang: 'zh-CN',
  title: '组件库',
  description: '基于 vuepress 的组件库文档',
  theme: defaultTheme({
    navbar: [
      {
        text: '指南',
        link: '/guide/design',
      },
      {
        text: '组件',
        link: '/components/input.md',
      }
    ],
    sidebar: {
      '/guide': [
         {
          text: '基础',
          collapsible: false,
          children: [
            {
              text: '设计',
              link: '/guide/design'
            }
          ]
        }
      ],
      '/components': [
        {
          text: 'Basic 基础组件',
          collapsible: false,
          children:[]
        },
        {
          text: 'Form 表单组件',
          collapsible: false,
          children: [
            {
              text: 'Input 输入框',
              link: '/components/input'
            },
            {
              text: 'Select 选择器',
              link: '/components/select'
            }
          ]
        }
      ]
    },
    sidebarDepth: 1
  }),
  base: '/demo/'
})

客户端配置文件

在大多数情况下，配置文件已经足够帮助你配置好你的 VuePress 站点。不过，有些时候用户们可能希望直接添加一些客户端代码。 VuePress 通过客户端配置文件来支持这种需求，在.vuepress 目录下，创建 client.js 或者 client.ts。结构如下：

在 client.js 文件中，可以引入第三方的库。比如 element plus 或者 自有组件库。 对于自有组件库的引入，还需要注意引入的时机： 1.自有组件库，直接引入：

首先，对页面的影响：

1. 组件库的示例，不能正常显示和执行；
2. 控制台的警告信息

对打包的影响，直接会影响打包结果

其原因就是：这是因为vuepress build生成的静态文件都是通过node服务端渲染完成的。因此，当组件中不是在beforeMount 或者 mounted 钩子中访问浏览器 / DOM 的 API时，就会有问题。 所以需要改为客户端再去加载自有组件库：

这样，页面就可以显示了。build 的时候也不会出现问题了；