使用vitepress构建组件库文档

前期调研

Vitepress

• 官方文档：https://vitepress.vuejs.org/

  • Vitepress是在Vite之上构建的Vue驱动的静态站点生成器。
  • Vitepress 被称为“ Vuepress的小弟弟”，它比同类产品具有一些优势。

• 建立在Vite而非Webpack上，因此启动时间，热重装等更快

• 使用Vue3来减少JS的有效负载

• 轻量级

Vitepress 能够实现这些目标的一个原因是，它比Vuepress 更具体，而 Vuepress在过去几年里变得更加复杂。

虽然不打算完全取代Vuepress作为 Vue 的静态网站生成器，但 Vitepress 提供了一种轻量级的替代方案。 对于大多数项目，例如文档和简单站点，Vitepress的特殊性和简约性将使开发变得轻而易举

官方文档提示

• VitePress 目前处于 0.x 状态。它已经适合开箱即用的文档使用，但配置和主题 API 可能仍会在次要版本之间发生变化。
• 这个早期的WIP（可理解成在制品），目前主要精力专注于Vite的稳定和功能的完整，对于一些serious的事不建议使用它！

PS：偶然发现element-plus的组件库文档就是使用VitePress，放心用住！！！

优势

• 它相当于VuePress，当它将Vue2换成Vue3，把webpack换成vite，因此：
  • 它有VuePress的所有优点；如：可以在md里面混合vue组件等；
  • 具有Vite的速度；如：可以秒开一个VitePress开发服务器以及md的编辑也会瞬间更新
  • 利用Vue3的一些高阶特性，做了一些更细致的优化；如避免纯静态内容的double payload（双重负载）和hydration开销
• 两款支持vitepress的demo展示插件vitepress-theme-demoblock和vitepress-for-component。

安装VitePress

• 初始化

  • 如果mkdir && echo '# Hello VitePress' > docs/index.md没有效果，可以自己手动创建

  yarn init
  yarn add --dev vitepress
  mkdir && echo ‘# Hello VitePress’ > docs/index.md

• 添加命令到package.json

  “scripts”: {
  “docs:dev”: “vitepress dev docs”,
  “docs:build”: “vitepress build docs”,
  “docs:serve”: “vitepress serve docs”,
  },

• 启动本地服务

  • http://localhost:3000/可以看到初始化的页面

  yarn docs:dev

配置VitePress

• 在 docs 目录下创建 .vitepress 目录即可开始设置配置

  • 在.vitepress中新建config.js文件进行配置
  • 实现侧边栏，导航栏及搜索框

  module.exports = {
  title: ‘Kylin’,
  description: ‘Just playing around.’,
  lang: ‘en-US’,
  themeConfig: {
  // 展示搜索框
  algolia: {
  appKey: ‘’,
  indexName: ‘’,
  searchParameters: {
  faeFilters: [‘tags:guide,api’]
  }
  },
  nav: [{
  text: ‘首页’,
  link: ‘/’,
  },
  {
  text: ‘GitHub’,
  link: ‘https://github.com/lxKylin/vitepressdemo’,
  },
  ],
  // 侧边栏
  sidebar: {
  ‘/’: getDemoSidebar(),
  }
  },
  markdown: {
  config: (md) => {
  const {
  demoBlockPlugin
  } = require(‘vitepress-theme-demoblock’)
  md.use(demoBlockPlugin)
  }
  }
  }

  function getDemoSidebar() {
  return [
  {
  text: “介绍”
  },
  {
  text: “更新日志”,
  children: [{
  text: “新特性”,
  link: “/components/log/”
  }]
  },
  {
  text: “开发指南”,
  children: [{
  text: “安装”
  }]
  },
  {
  text: “快速开始”,
  link: “/”
  },
  {
  text: “基础组件”,
  children: [{
  text: “Button 按钮”,
  link: “/components/button/”
  },
  {
  text: “Icon 图标”,
  link: “/components/icon/”
  },
  ],
  },
  {
  text: “布局组件”,
  },
  ]
  }

• 效果图如下

创建Button按钮展示

• 创建docs/components/button/index.md文件

  • 可以在该文件中使用markdown语法随便写入内容

  // docs/components/button/index.md

  Button 按钮

  <template>
    <button>按钮</button>
  </template>
  

• 效果图

组件显示与代码的展开关闭

• 需要用到vitepress-theme-demoblock插件

  npm install -D vitepress-theme-demoblock
  # or
  yarn add -D vitepress-theme-demoblock
  

  • 这个插件不可以避免展示组件和代码需要重复写两遍的问题

    • 将这个插件，注册到vitepress的config.js中（上述代码中已经写入）

      module.exports = {
      markdown: {
      config: (md) => {
      const { demoBlockPlugin } = require(‘vitepress-theme-demoblock’)
      md.use(demoBlockPlugin)
      }
      }
      }

注入主题与插件

• 在docs/.vitepress/theme/index.ts中注册

  • 其中register-components.js不需要自己创建，在package.json中注入脚本，执行脚本自动生成在docs/.vitepress/theme目录下

  “scripts”: {
  “register:components”: “vitepress-rc”
  }

  yarn register:components

  // 导入vitepress-theme-demoblock主题，并注册组件(包含主题中默认的组件)。
  import Theme from ‘vitepress/dist/client/theme-default’

  // 导入主题样式
  import ‘vitepress-theme-demoblock/theme/styles/index.css’

  // 导入插件的主题
  import { registerComponents } from ‘./register-components.js’

  export default {
  …Theme,
  enhanceApp({ app }) {
  registerComponents(app)
  }
  }

效果

• 在需要展示的demo中的index.md文件中使用特定的语法包裹代码，可以自动生成组件demo展示

  • 比如在docs/components/button/index.md中
  • :::demo是描述部分
  • 使用的是最初的button，最初只为展示出组件，后续再研究怎么封装

  Button 按钮

  :::demo 使用type，plain，round来定义 Button 的样式

  <template>
    Small
    <button style="color: red">按钮1</button>
    Middle
    <button type="size">按钮2</button>
    Large
    <button>按钮3</button>
    Disabled
    <button disabled>按钮4</button>
  </template>
  

  :::

• 具体代码可见GitHub：https://github.com/lxKylin/vitepressdemo