vitepress搭建组件库文档

前端开发工作，肯定会使用到组件库，随着技术的提升也会搭建自己的组件库，那像其它的组件库那样的文档是怎么做出来的呢？废话不多说，我们采用最新的vitepress来搭建文档，直接开始从0搭建！

项目准备

以下是我的环境版本

nodejs v16.13.0
npm v8.1.0

项目创建

首先新建文件夹vitepress-demo，然后进入到创建好的目录cd vitepress-demo执行初始化命令：

$ npm init -y

安装我们需要的依赖：

$ npm install vitepress vitepress-theme-demoblock -D

接着在package.json中增加我们script命令用于启动服务和打包（docs是我们等会要存放我们文档代码的目录名称）：

到这里我们的准备工作就完成了！

基础主页搭建

首先我们先建一下我们的代码目录解构，然后在写代码,如下：

|-- vitepress-demo
    |-- docs # 我们文档目录
        |-- index.md # 入口主页
        |-- .vitepress # vitepress的相关文件
        |   |-- configs # vitepress抽离出来的配置统一放在这里，方便维护
        |   |-- theme # vitepress主题的一些配置
        |   |-- config.js # vitepress配置文件
        |-- components # 组件文档存放的目录
        |-- guide # 组件库指南目录
        |-- public # 公共的一些资源，如logo等

先在index.md中加入主页的内容,这里我就先用vite官网的样式，有需要自己修改：

---
home: true
heroImage: /logo.svg
actionText: 开始
actionLink: /guide/install

altActionText: 了解更多
altActionLink: /components/basic/button

features:
    - title: 💡 Instant Server Start
      details: On demand file serving over native ESM, no bundling required!
    - title: ⚡️ Lightning Fast HMR
      details: Hot Module Replacement (HMR) that stays fast regardless of app size.
    - title: 🛠️ Rich Features
      details: Out-of-the-box support for TypeScript, JSX, CSS and more.
    - title: 📦 Optimized Build
      details: Pre-configured Rollup build with multi-page and library mode support.
    - title: 🔩 Universal Plugins
      details: Rollup-superset plugin interface shared between dev and build.
    - title: 🔑 Fully Typed APIs
      details: Flexible programmatic APIs with full TypeScript typing.
footer: MIT Licensed | Copyright © 2021-present WQ
---

接着配置一下vitepress，在.vitepress/config.js中.先配置一下基础的标题和网站logo：

module.exports = {
    title: "@wq/components", // 标题
    description: 'Life is short, Keep it simple.', // 描述信息
    head: [  // 网站头部的配置
        ['link', { rel: 'icon', type: 'image/svg+xml', href: '/logo.svg' }]
    ],
};

这样我们的主页就算完成了，npm run dev启动一下看一下我们的效果：

// base是我们的发布路径，默认为/，可以在环境变量中自行配置
const base = process.env.BASE || '/'
// nav导航我们抽离在configs下面nav.js文件，方便管理
const nav = require('./configs/nav')

module.exports = {
    title: "@wq/components",
    description: 'Life is short, Keep it simple.',
    head: [
        ['link', { rel: 'icon', type: 'image/svg+xml', href: '/logo.svg' }]
    ],
    base: base,
    themeConfig: {
        nav
    },
};

在configs/nav.js中，导出我们的导航配置（没有的文件需要大家自行创建，后面就不多说了）如下：

// 指南默认跳转到我们guide目录下的install也就是安装页面
module.exports = [
    { text: '指南', link: '/guide/install', activeMatch: '^/guide/' }
]

创建guide/install.md,里面随意写点东西

重启项目看一下我们的导航，点击指南，可以看到已经成功了：

组件

这里我们用element-plus作为我们的组件库展示，大家可以自行安装自己的组件库

先安装一下element-plus：

$ npm install element-plus

首先需要把组件注册，不然组件怎么使用呢？在.vitepress/theme/index.js中注册我们的组件：

// vitepress-theme-demoblock是vitepress的一个主题插件，可以去github查看
// 组件注册就和我们平时开发vue项目一样
import theme from 'vitepress/dist/client/theme-default'
import 'vitepress-theme-demoblock/theme/styles/index.css'
// Demo组件和DemoBlock是两个vue组件，等会我们要在md文件中使用他来展示组件
import Demo from "vitepress-theme-demoblock/components/Demo.vue";
import DemoBlock from "vitepress-theme-demoblock/components/DemoBlock.vue";

import ElementPlus from 'element-plus'
import 'element-plus/dist/index.css'

// enhanceApp方法传很多方法进来，感兴趣的可以去官网查看，比如app、router等，这里我们需要使用app实例来注册我们的组件
export default {
  ...theme,
  enhanceApp({ app }) {
    app.use(ElementPlus)
    app.component("Demo", Demo);
    app.component("DemoBlock", DemoBlock);
  }
}

然后配置一下我们的markdown，.vitepress/config.js中的增加配置项：

// 具体的配置可以去看官网文档，这里不多做详细解释，
...
markdown: {
    anchor: { permalink: false },
    toc: { includeLevel: [1, 2] },
    config: (md) => {
      const { demoBlockPlugin } = require('vitepress-theme-demoblock')
      md.use(demoBlockPlugin);
    }
  }
...

准备工作完成了，我们在导航中加入我们的组件导航，configs/nav.js中,代码很少，大家自己写一下：

在components/basic/button.md中来写我们的组件文档，内容大家自己写一下，我这边是直接去element-plus官网copy过来做个演示，需要用:::demo :::包裹代码块，```vue ```代表是我们的vue代码

修改了我们的配置文件需要重启一下项目，我们重启一下查看效果：

sidebar

sidebar也就是我们侧边显示的导航，我们来优化一下

在configs/sidebar.js中:

module.exports = {
  "/guide/": getGuideSidebar(),
  "/components/": getComponentsSidebar(),
}

function getComponentsSidebar() {
  return [
    {
      text: 'Basic 基础组件',
      children: [
        {
          text: 'Button 按钮',
          link: '/components/basic/button'
        }
      ]
    }
  ]
}

function getGuideSidebar() {
  return [
    {
      text: '基础',
      children: [
        {
          text: '安装',
          link: '/guide/install'
        }
      ]
    }
  ]
}

接着修改一下配置文件config.js：重启一下项目，查看修改后的效果，我这边随便多加了一些菜单，大家可以自行修改：

到这里我们的组件文档主要用法就差不多了，还有一些样式什么的优化的东西大家可以根据自己的喜好，看文档自行修改，后面也会出一些系列文章，来从0讲解一些自己理解的东西，欢迎大家关注，有想看的东西也欢迎大家下方评论，有时间我会整理并分享，手写不易，点个赞吧------WQ

使用vitepress从0搭建自己的组件库文档

vitepress搭建组件库文档

项目准备

项目创建

基础主页搭建

导航

组件

sidebar