使用vue-press搭建一个像element一样的组件文档

系列文章目录

VuePress 2.0 在 2021 年中旬发布,由webpack改为使用vite进行构建。在vuePress1.0时代，很好的解决了vuePress使用webpack打包构建缓慢的问题。但现在使用vuePress 是更好的选择！！！

---

---

前言

现在常见的一些文档生成工具有如下几种

• Gatsby - 以 GraphQL 为核心，功能相当完善，插件生态丰富。但学习曲线高（React）
• Docusaurus - Meta 公司出品。功能强大，与 Gatsby 相似（React）
• dumi - 一款 UmiJS 生态中的组件开发文档工具（React）
• Nextra - 一个基于 Next.js 的静态站点生成器。（React）
• VuePress - 包含由 Vue 驱动的主题系统和插件 API，另一个部分是为书写技术文档而优化的默认主题（Vue）
• VitePress - 对 VuePress 进行了不少的改进。VitePress 旨在降低当前 VuePress 的复杂性，并从其极简主义的根源重新开始。（Vue）

---

一、为什么选择VuePress而非VitePress

除了 VitePress 之外，其他都是用 Webpack 作为开发服务器。一个只有几页的简单文档站点启动开发服务器所花费的时间变得难以忍受。即使是 HMR 更新也可能需要几秒钟才能反映在浏览器中。Vite 的出现很好地解决了这些问题：近乎即时的服务器启动、仅编译所服务页面的按需编译以及闪电般快速的 HMR。

一、安装VuePress

下载

mkdir docs && cd mkdir
npm init -y 
npm i vuepress 

项目初始化后，在package.json配置启动命令,方便调试

 "scripts": {
    "dev":"vuepress dev", #开发启动(热加载有点问题，部分文件无法监听，如果遇到改变文件后不更更新，手动npm run dev重启服务)
    "build":"vuepress build" #打包
  },

二、项目结构

.
├── docs
│   ├── .vuepress (可选的)
│   │   ├── components (可选的)
│   │   ├── theme (可选的)
│   │   │   └── Layout.vue
│   │   ├── public (可选的)
│   │   ├── styles (可选的)
│   │   │   ├── index.styl
│   │   │   └── palette.styl
│   │   ├── templates (可选的, 谨慎配置)
│   │   │   ├── dev.html
│   │   │   └── ssr.html
│   │   |── config.js (可选的)
│   │   └── enhanceApp.js (可选的)
│   │ 
│   ├── README.md (进入文档时显示的首页，类似于element文档的起步页,可以自主配置)
│   └── guide
│      └── README.md (指南页)
│   
└── package.json

• docs/.vuepress: 用于存放全局的配置、组件、静态资源等。
• docs/.vuepress/components: 该目录中的 Vue 组件将会被自动注册为全局组件。
• docs/.vuepress/theme: 用于存放本地主题。
• docs/.vuepress/styles: 用于存放样式相关的文件。
• docs/.vuepress/styles/index.styl: 将会被自动应用的全局样式文件，会生成在最终的 CSS 文件结尾，具有比默认样式更高的优先级。
• docs/.vuepress/styles/palette.styl: 用于重写默认颜色常量，或者设置新的 stylus 颜色常量。
• docs/.vuepress/public: 静态资源目录。
• docs/.vuepress/templates: 存储 HTML 模板文件。
• docs/.vuepress/templates/dev.html: 用于开发环境的 HTML 模板文件。
• docs/.vuepress/templates/ssr.html: 构建时基于 Vue SSR 的 HTML 模板文件。
• docs/.vuepress/config.js: 配置文件的入口文件，也可以是 YML 或 toml。
• docs/.vuepress/enhanceApp.js: 客户端应用的增强。

三、基础文件

docs/README.md 是默认的文档进入首页，有一个通用的模板文件，使用它diy即可

docs/docs/README.md

---
home: true #是否是首页
heroText: Hero 标题
tagline: Hero 副标题
actionText: 快速上手 →
actionLink: /zh/guide/
features:
  - title: 简洁至上
    details: 以 Markdown 为中心的项目结构，以最少的配置帮助你专注于写作。
  - title: Vue驱动
    details: 享受 Vue + webpack 的开发体验，在 Markdown 中使用 Vue 组件，同时可以使用 Vue 来开发自定义主题。
  - title: 高性能
    details: VuePress 为每个页面预渲染生成静态的 HTML，同时在页面被加载的时候，将作为 SPA 运行。
footer: MIT Licensed | Copyright © 2018-present Evan You
---

三、配置文件

docs/.vuepress/config.js 基本配置

一个完整的项目文档，下面的配置已经非常全面。但你仍然可以查看更多内容请参考vuepress 基本配置

module.exports = {
 title: "wui", //文档标题
 description: "官方文档", //文档描述
 base: "/", //设置访问前缀 设置/base后，访问地址为http://localhost:8080/base
 port: "8080",
 plugins: ["demo-container"],
 themeConfig: {
   // 顶部导航栏
   nav: [
     {
       text: "起步",
       link: "/",
     },
     {
       text: "指南",
       link: "/guide/",
       target: "_blank", //_blank打开一个新窗口 _self在内部打开
     },
     {
       text: "组件",
       link: "/components/",
       items:[ //多级导航
         {
           text:"二级目录",
           link:"/components",
           items:[{
             text:"三级目录",
             link:"/components" //最多三级
           }]
         }
       ]
     },
   ],
   sidebarDepth: 0, //0读取1级标题 1读取1级和2级标题 2读取1级、2级、3级标题
   // 侧边栏
   // sidebar: [
   //   "/components/alert",//会根据/components/alert.md中配置的(#标题)自动生成(侧边栏title),读取的标题层级由sidebarDepth决定
   //   ["/components/button","手动设置侧标了title"] 作用于分组内部的实验
   // ],
   // 分组排列
   sidebar: [
     {
       path: "/components/alert", //分组默认地址
       title: "基本组件", //分组标题
       sidebarDepth: 1,//作用在项内部的层级，优先级比外部的更高
       children: [
         "components/alert", //分组内部项
         ["components/button", "手动设置侧标了title"],
       ],
     },
   ],
 },
 chainWebpack: (config, isServer) => {
   // config 是 ChainableConfig 的一个实例
   config.entry("index").add("element-ui/lib/theme-chalk/index.css");
 },
};

---

docs/.vuepress/enhanceApp.js 可以在这里面通过访问Vue构造函数，实现对一些组件或插件的注入

由于 VuePress 是一个标准的 Vue 应用，你可以通过创建一个 .vuepress/enhanceApp.js 文件来做一些应用级别的配置，当该文件存在的时候，会被导入到应用内部。enhanceApp.js 应该 export default 一个钩子函数，并接受一个包含了一些应用级别属性的对象作为参数。你可以使用这个钩子来安装一些附加的 Vue 插件、注册全局组件，或者增加额外的路由钩子等：

// 使用异步函数也是可以的
export default ({
 Vue, // VuePress 正在使用的 Vue 构造函数
 options, // 附加到根实例的一些选项
 router, // 当前应用的路由实例
 siteData, // 站点元数据
 isServer // 当前应用配置是处于 服务端渲染 或 客户端
}) => {
 // ...做一些其他的应用级别的优化
}

四、进阶操作

1、自动化生成侧边栏目录

2、使用自定义主题

3、增加组件案例演示

五、一些比较好用的库

• 自动生成 vuepress-bar
• demo容器，可以像element一样在文档中放入示例demo

六、 在搭建组件库时不得部考虑的一些问题及解决方案

1. 组件库中每增加一个组件，是否可以自动生成对应的md文件，并同时生成侧边栏目录
2. 是否可以自动读取组件中需要参数，并生成对应的文档数据
3. 是否可以在文档上增加组件的演示操作