配置VitePress组件库文档并且发布 | 青训营笔记

Sijiw
602 阅读4分钟

这是我参加第五届青训营伴学笔记创作活动的第10天。

VitePress构建完成之后，需要对文档进行配置，比如配置侧边栏、引入组件库等，让它变得完整一些。

之前完成了使用VitePress对组件库文档进行了构建，但是还没有具体配置过config和theme文件。

配置sidebar和nav

sidebar

sidebar的配置可以写成类似下列的格式：

export const sidebar = {
  '/': [
    {
      text: 'Basic 通用组件',
      items: [
        { text: 'Button 按钮', link: '/components/button/' },
        { text: 'Layout 布局', link: '/components/layout/' },
        { text: 'Icon 图标', link: '/components/icon/' },
        { text: 'Container 布局容器', link: '/components/container/' }
      ]
    },
  ],
  ...
}

sidebar是一个对象的形式，key是你的文档的路径，value是一个数组，表示这个路径里的页面。

上述代码中，这个数组里是一堆对象，每个对象都有对应的text和items，text对应这个板块的标题，会以黑色加粗在文档中显示，items是类似子菜单的链接，里面也有一个text，表示链接的文字内容，link是这个链接该导航到的位置。这个链接的导航会根据你的docs下的目录去寻找对应的文件来展示到浏览器的页面当中。

nav

比起sidebar，nav的配置就比较简单。nav是一个数组，里面存的都是顶部每一项链接，以对象形式存储。每一个对象都像sidebar里的items一样，有一个text，一个link，意义与sidebar相同。

配置theme

在theme/index.ts里，你可以引入自己的组件库，或者引入一些组件等，就像常规项目的mainh.ts一样。

添加查看代码的demo

当我们写好了一个组件的文档，但是想展示代码给用户看，该怎么办？

VitePress支持在markdown里写vue的语法，你可以写一个vue组件，然后读取引入的文档组件的代码内容......

但是这样做太麻烦了，编写起来也有一点难度。

好在有现成的插件可以使用。推荐使用vitepress-demo-preview这个插件。在掘金大多数关于VitePress的文章，介绍的几乎就3个插件：vitepress-theme-demoblock、vitepress-demo-preview、vitepress-demoblock，但使用体验最好的我觉得是vitepress-demo-preview。

要使用这个插件，首先需要安装@vitepress-demo-preview/component、@vitepress-demo-preview/plugin这两个包，并且使用-D保存到开发环境。

安装好之后，在theme里引入

import {
  AntDesignContainer,
  ElementPlusContainer
} from '@vitepress-demo-preview/component'
import '@vitepress-demo-preview/component/dist/style.css'

export default {
  ...DefaultTheme,
  enhanceApp: async ({ app, router, siteData }) => {
    app.component('demo-preview', ElementPlusContainer)
  }
}

引入的代码如上所示，你也可以导入DefaultTheme，这个是VitePress的默认主题。

vitepress-demo-preview里有Ant Design和Element Plus两种展示方式的代码预览组件，可以自己选一个使用。

回到config.ts，在默认暴露的对象里，添加一个markdown成员，引入vitepress-demo-preview的markdown插件。

import {
  componentPreview,
  containerPreview
} from '@vitepress-demo-preview/plugin'
import { nav } from './config/nav'
import { sidebar } from './config/sidebar'

markdown: {
    config(md) {
      // md.use(demoBlockPlugin)
      md.use(containerPreview)
      md.use(componentPreview)
    }
}

这样，可预览代码的插件就配置好了。

在markdown里使用预览代码

因为刚才在theme里已经全局注册了这个组件，所以可以不用再次引入

在markdown中写入如下代码：

<preview path="./demo.vue" title="Avatar" description="description"></preview>

path是你的展示组件的一个demo路径，title和description是类似在Ant Design文档中的标题和描述，这两个属性在插件里的Element预览组件不显示，但是需要填写内容，否则会报错。

这样，一个组件库文档已经完全建立好了，接下来可以发布了。

发布

这里以发布到Github Pages为例。

将你的文档使用docs:build打包，打包的产物在docs/.vitepress/dist目录中。进入dist目录，将所有文件提交到仓库中，然后在仓库的设置中，点击Page，设置你文档所在的分支。

注意，如果需要部署到Github Pages，你需要配置config的base，配置如下：

base: '/<RepoName>/',

RepoName是你的仓库的名字，这是因为部署之后，你的路径会变成xxx.io/RepoName/的形式。

总结

组件库文档的构建、配置、发布就此告一段落，讲解的只是冰山一角，更多详细的配置可以查看VitePress的官方文档。

avatar
文章
阅读
粉丝