使用vitepress构建组件库文档

使用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 按钮

```vue
<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 的样式

```vue
<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