VuePress 避坑指南

写在前面

继上次 浅尝 | 从 0 到 1 Vue 组件库封装 后，还有一项看似简单，却又非常重要的东西还没有完成，那就是组件库的在线开发文档的编写，搭建在线开发文档的流程并不复杂，接下来分享我搭建的流程，做个学习笔记，也顺便供需要搭建的朋友做个参考，有问题欢迎指出哟！

什么是 VuePress

作为开发者，我们都知道开发文档的重要性，组件的开发文档是否完善、是否清晰，基本上决定了广大开发者是否有意愿使用它，相信每一个 Coder 或多或少都曾在某个月黑风高夜，情绪过激得狂喷过某些开发文档，而当我们着手搭建、开发自己的一套组件库的时候，也许是公司业务需要，也许是自己满腔的开源热忱，而在这两种不同的场景下，不变的是擅长在月黑风高夜频繁国粹的coder，那么，如何写好开发文档呢，工欲善、先利器 ，作为 Vue 生态下广受好评的一员， VuePres 非常适用于编写技术文档，可以说 Vuepress 就是为技术文档而生，正如VuePress 官网所说的，简单至上，VuePress 提供了一个极简的方式，让开发者能够最高效地完成相关技术文档的编写，成为一个 coder 届社会主义好公民！

安装环境

这里基于博主之前文章《浅尝 | 从 0 到 1 Vue 组件库封装》的基础上搭建，所以运行命令的目录为组件库根目录

// 安装vuepress
npm install -D vuepress
// 创建存放文档的目录以及根 md
mkdir docs && echo '# Hello VuePress' > docs/README.md

在 package.json中添加 VuePress 启动脚本命令

"docs:dev": "vuepress dev docs",
"docs:build": "vuepress build docs"

运行脚本命令，成功启动 VuePress

npm run docs:build

根据 VuePress 官方的要求搭建目录结构

写入基础配置

在 /docs 中新建 VuePress 配置入口 /docs/.vuepress/config，并写入基础配置

// .vuepress/config.js
module.exports = {
  themeConfig: {
    sidebar: [
      '/',
      '/componentDoc/FirstComponent'
    ]
  }
}

创建组件目录

在 /docs 中创建 componentDoc 用于存放每个组件的 .md 文件

创建组件对于的 .md 文件

在 /docs/componentDoc 中创建FirstComponent.md 并添加标题，重启VuePress,可以发现已经成功创建了一个侧边栏标签

引入 Vue 组件

在 /docs/.vuepress 中新建配置文件 enhanceApp.js 并将组件库引入

import 'yimwu-ui/dist/css/index.css'
import YIUI from 'yimwu-ui';

export default ({ Vue }) => {
  Vue.use(YIUI)
}

另一种引入方式是直接将 Vue 组件存放到 /docs/.vuepress/components 中，vuepress将自动引入components中的所有组件

在 componentDoc/FirstComponent 中使用组件

使用组件时所需要引用的静态文件可存放在 /docs/.vuepress/public 静态目录中

总结

搭建 vuepress 非常简单，不需要过多的配置，就可以将开发文档整理成比较清晰的结构，初步搭建算是完成了，不过后面其实还有很多值得扩展的东西，比如更换更加好看的主题、添加动态测试组件参数的插件等等，先挖个坑，后期有空来填！

写在最后

博主接下来将持续更新好文，欢迎关注博主哟！！
如果文章对您有帮助麻烦亲点赞、收藏 + 关注和博主一起成长哟！！❤❤❤