使用 VitePress@1.0.0-rc.36 编写组件库文档

0. 前言

VitePress 官方网站：https://vitepress.dev/zh/

public 目录：https://vitepress.dev/zh/guide/asset-handling#the-public-directory

vitepress 的根目录是 docs，其子目录 public 和脚手架项目中的 public 目录一样，都是共享资源目录，直接通过 /xxx 即可访问到 public/xxx 中的资源 xxx

1. 初始化环境

官方链接：快速开始 | VitePress

1. 创建 your-components-lib-doc 文件夹

2. 生成 package.json 包管理文件

   npm init -y
   

3. 安装 vitepress

   cnpm i -D vitepress
   

4. 在 package.json 中新增下面的脚本

   {
     ...
     // 三条命令最后的是文档的存放目录：一般目录名称设置为根目录下的 docs 目录
     "scripts": {
       "dev": "vitepress dev docs",
       "build": "vitepress build docs",
       "preview": "vitepress preview docs"
     },
     ...
   }
   

上面第 4 步可以替换为下面的步骤：

 npx vitepress init

2. 编写主页

官方链接：

• https://vitepress.dev/zh/reference/frontmatter-config
• https://vitepress.dev/zh/reference/default-theme-home-page

1. 在项目根目录下新建 docs 目录，然后新建 index.md

   ---
   # 启用主页布局
   layout: home
   
   # Hero 部分位于主页顶部
   hero:
     # 组件库名称
     name: your-components-lib
     # 组件库文档标题
     text: 二次封装elemnent-plus
     # 描述（子标题）
     tagline: 高扩展的组件库
     # 组件库 logo 图片
     image:
       src: /logo.webp
       alt: VitePress
     # 按钮组：点击可以跳转
     actions:
       # 主题
       - theme: brand
         # 按钮文本
         text: 快速开始
         # 跳转链接
         # 跳转到 `/quickStart/index.md` 页面
         link: /quickStart/
   
   # 组件库特性描述
   features:
     - # 图标
       icon: 🛠️
       # 标题
       title: 简洁至上
       # 描述信息
       details: 所有组件支持全量引入和按需引入，并且用法简单
     - icon: 📝
       title: 高扩展性
       details: 全新的组件 api 设计，支持高度自定义
     - icon: 🚀
       title: 全面覆盖
       details: 涵盖基础组件、通用组件和业务组件
   ---
   

3. 编写文档网站头部导航和侧边导航

官方链接：站点配置 | VitePress

1. 在 docs/.vitepress/ 目录下新建 config.js 配置文件

   import { defineConfig } from 'vitepress'
   
   // https://vitepress.dev/zh/reference/site-config#config-intellisense
   // 使用 defineConfig 包裹配置文件，在支持的 IDE 中会有智能提示
   export default defineConfig({
     // 网站标题（相当于设置 head 中的 title 标签）
     title: 'xxx',
     // 部署的基础路径
     base: '/',
     // 配置网站的 head 标签信息
     head: [],
     themeConfig: {
       // 头部导航
       // https://vitepress.dev/zh/reference/default-theme-nav#navigation-links
       nav: [
         {
           // 导航名称
           text: '首页',
           // 跳转的项目链接
           link: '/',
         },
         {
           text: 'github站点',
           // github 的部署地址
           link: 'xxx',
         },
         {
           text: 'gitee站点',
           // gitee 的部署地址
           link: 'xxx',
         },
       ],
       //在导航栏中展示带有图标的社交帐户链接
       // https://vitepress.dev/zh/reference/default-theme-config#sociallinks
       socialLinks: [
         {
           icon: 'github',
           // 链接网址
           link: 'xxx',
         },
       ],
       // 侧边导航（在 siderbar 配置的跳转页面中才会显示）
       // https://vitepress.dev/zh/reference/default-theme-sidebar#the-basics
       sidebar: [
         {
           // 一级导航标题
           text: '介绍',
           link: '/intro/',
           // items: [
           //   {
           //     // 二级导航标题
           //     text: '介绍',
           //     // 跳转到 `/intro/index.md` 页面
           //     link: '/intro/',
           //   },
           // ],
         },
         {
           text: '快速上手',
           link: '/quickStart/',
         },
         ...
       ],
     },
   })
   

4. 集成组件库并添加显示和交互

1. 从 npm 仓库中下载开发好的组件库和对等依赖 element-plus、@element-plus/icons-vue

   cnpm i element-plus @element-plus/icons-vue your-components-lib
   

2. 新建 docs/.vitepress/theme/index.js

   导入组件库和必要依赖，然后进行注册

   import DefaultTheme from 'vitepress/theme'
   import ElementPlus from 'element-plus'
   import 'element-plus/dist/index.css'
   import * as ElementPlusIconsVue from '@element-plus/icons-vue'
   import miniUI from 'your-components-lib'
   import 'your-components-lib/style.css'
   
   export default {
     ...DefaultTheme,
     enhanceApp({ app }) {
       // 全局注册图标组件
       for (const [key, component] of Object.entries(ElementPlusIconsVue)) {
         app.component(key, component)
       }
       // app 相当于通过 Vue 的 createApp({...}) 创建的 vue 实例
       app.use(ElementPlus)
       app.use(miniUI)
     },
   }
   

3. 在 markdown 页面中使用组件库的组件

   官方链接：在 Markdown 使用 Vue | VitePress

   # 图标选择器
   
   用户点击按钮，弹出框显示所有图标，点击图标可以复制图标代码。
   
   ## 基础用法
   
   <div style="padding: 1em; margin: 1em; border: 1px solid #eee;">
   <!-- 自定义组件最终会被解析成对应的组件 -->
   <choose-icon title="选择图标" v-model:visible="visible">选择图标</choose-icon>
   </div>
   
   <script lang="ts" setup>
   import { ref } from "vue"
   
   const visible = ref<boolean>(false)
   </script>
   
   ## 代码示例
   
   ```vue
   <template>
     <!-- 自定义组件最终会被解析成对应的组件 -->
     <choose-icon title="选择图标" v-model:visible="visible">
       选择图标
     </choose-icon>
   </template>
   
   <script lang="ts" setup>
   import { ref } from 'vue'
   
   const visible = ref<boolean>(false)
   </script>
   ```
   

   上述的 markdown 中可以编写 vue 代码

5. 组件预览插件

• 插件仓库地址：https://www.npmjs.com/package/@vitepress-demo-preview/plugin