使用VitePress搭建及部署vue組件庫(kù)文檔的示例詳解

更新時(shí)間：2022年08月18日 16:34:21 作者：迪迪滴

這篇文章主要介紹了使用VitePress搭建及部署vue組件庫(kù)文檔,本文以element-plus作為示例來(lái)搭建一個(gè)文檔，結(jié)合實(shí)例代碼給大家介紹的非常詳細(xì)，需要的朋友可以參考下

每個(gè)組件庫(kù)都有它們自己的文檔。所以當(dāng)我們開(kāi)發(fā)完成我們自己的組件庫(kù)必須也需要一個(gè)組件庫(kù)文檔。如果你還不了解如何搭建自己的組件庫(kù)可以看這里->從零搭建Vue3組件庫(kù)?？赐赀@篇文章你就會(huì)發(fā)現(xiàn)原來(lái)搭建和部署一個(gè)組件庫(kù)文檔是那么的簡(jiǎn)單。當(dāng)然部署也不需要你有自己的服務(wù)器，你只要有g(shù)ithub即可。由于我們的組件庫(kù)還沒(méi)有完成，所以下面就以element-plus作為示例來(lái)搭建一個(gè)文檔吧。

安裝vitepress

首先新建文件夾就叫kittydocs,執(zhí)行pnpm init初始化，然后安裝vitepress

pnpm add vitepress -D

在package.json添加一些script

 "scripts": {
    "docs:dev": "vitepress dev docs",
    "docs:build": "vitepress build docs",
    "docs:serve": "vitepress serve docs"
  }

安裝組件庫(kù)element-plus

pnpm i element-plus -S

目錄結(jié)構(gòu)

新建kittydocs目錄，其中文件結(jié)構(gòu)如下圖

.vitepress/config.js為配置文件
.vitepress/theme/index.js為自定義主題
examples作為為組件示例目錄
public是公共文件目錄
index.md則是組件庫(kù)文檔的首頁(yè)
gulild放我們組件指南文檔

文檔首頁(yè)

首先我們按照官網(wǎng)的樣式給我們組件庫(kù)整個(gè)首頁(yè)，在index.md文件中寫(xiě)入

---
layout: home

title: Kitty
titleTemplate: 一個(gè)Vue3組件庫(kù)

hero:
  name: Kitty
  text: 一個(gè)Vue3組件庫(kù)
  tagline: 沒(méi)啥特點(diǎn)僅供學(xué)習(xí)
  image:
    src: /logo.png
    alt: Kitty
  actions:
    - theme: brand
      text: 開(kāi)始
      link: /guide/
    - theme: alt
      text: 在 Gitee 上查看
      link: https://gitee.com/geeksdidi/kittyui

features:
  - icon: ??
    title: Vue3組件庫(kù)
    details: 基于vite打包和TypeScript開(kāi)發(fā)
  - icon: ??
    title: 僅供學(xué)習(xí)使用
    details: 傾向于Vue3組件庫(kù)的學(xué)習(xí)，請(qǐng)勿用于實(shí)際生產(chǎn)項(xiàng)目
  - icon: ???
    title: 按需引入
    details: 直接支持按需引入無(wú)需配置任何插件。
---

然后pnpm run docs:dev啟動(dòng)我們的項(xiàng)目，我們就可以看到這樣的畫(huà)面

是不是感覺(jué)已經(jīng)有點(diǎn)組件庫(kù)文檔的意思了。接下來(lái)對(duì)導(dǎo)航欄以及我們們文檔的側(cè)邊欄進(jìn)行一個(gè)配置。

配置

導(dǎo)航欄配置

export default {
  themeConfig: {
    siteTitle: false,
    logo: "/logo.png",
    nav: [
      { text: "指南", link: "/guild/installation" },
      { text: "組件", link: "/examples/button/" },
    ],
    socialLinks: [{ icon: "github", link: "https://gitee.com/geeksdidi" }],
  },
}

我們?cè)赾onfig.js中配置我們的logo、導(dǎo)航欄以及社交鏈接。此時(shí)我們的導(dǎo)航欄便配置完成

側(cè)邊欄

首先我們對(duì)指南的側(cè)邊欄做一個(gè)配置

sidebar: {
      "/guild/": [
        {
          text: "基礎(chǔ)",
          items: [
            {
              text: "安裝",
              link: "/guild/installation",
            },
            {
              text: "快速開(kāi)始",
              link: "/guild/quickstart",
            },
          ],
        },
        {
          text: "進(jìn)階",
          items: [
            {
              text: "xx",
              link: "/xx",
            },
          ],
        },
      ],
    },

同時(shí)我們?cè)趃uild目錄下新建installation.md和quickstart.md文件。接下來(lái)分別在這兩個(gè)文件中介紹我們組件庫(kù)的安裝以及使用（這里將Element Plus當(dāng)作我們自己的組件KittyUI）

installation.md

# 安裝
## 環(huán)境支持
由于 Vue 3 不再支持 IE11，KittyUI 也不再支持 IE11 瀏覽器。
## 版本
Element Plus 目前還在開(kāi)發(fā)迭代中
## 使用包管理器
建議您使用包管理器 (NPM, Yarn, pnpm) 安裝 KittyUI, 然后您就可以使用打包工具，例如 Vite 和 webpack
# 選擇一個(gè)你喜歡的包管理器
# NPM
$ npm install kitty-ui --save
# Yarn
$ yarn add kitty-ui
# pnpm
$ pnpm install kitty-ui
## 瀏覽器直接引入
暫不支持

quickstart.md

# 快速開(kāi)始
本節(jié)將介紹如何在項(xiàng)目中使用 KittyUI
## 用法
...
<template>
  <Button>按鈕</Button>
</template>
<script setup>
    import { Button } from 'kitty-ui'
</script>
...

這時(shí)候我們文檔的效果如下

接下來(lái)我們對(duì)組件的側(cè)邊欄做一個(gè)配置,和指南一樣，我們只需要在sidebar下再加個(gè)/examples/路徑即可

 "/examples/": [
        {
          text: "基礎(chǔ)組件",
          items: [
            {
              text: "Button按鈕",
              link: "/examples/button/",
            },
            {
              text: "Icon圖標(biāo)",
              link: "/examples/Icon/",
            },
          ],
        },
      ],

vitepress中markdown文件中是可以直接使用vue組件的，我們先在theme/index全局引入element-plus

// .vitepress/theme/index.js

import DefaultTheme from "vitepress/theme";
import "element-plus/dist/index.css";
export default {
  ...DefaultTheme,
  enhanceApp: async ({ app, router, siteData, isServer }) => {
    // app is the Vue 3 app instance from `createApp()`. router is VitePress'
    // custom router. `siteData`` is a `ref`` of current site-level metadata.
    import("element-plus").then((module) => {
      app.use(module);
    });
  },
};

這里我們拿Button做一個(gè)演示，在button/index.md中我們可以直接這樣使用Button組件

<el-button>默認(rèn)按鈕</el-button>
<br/><br/>
<el-button>默認(rèn)按鈕</el-button>
<br/><br/>
<el-button type="primary">主要按鈕</el-button>
<br/><br/>
<el-button type="success">成功按鈕</el-button>
<br/><br/>
<el-button type="info">信息按鈕</el-button>

此時(shí)我們頁(yè)面即可展示我們的Button按鈕

基于此，我們便可以輕松使用markdown文件的形式來(lái)編寫(xiě)我們的組件使用文檔了。代碼有點(diǎn)長(zhǎng)，這里就貼一部分代碼展示與隱藏的實(shí)現(xiàn)部分

完整的md文檔你可以點(diǎn)擊 index.md 直接查看。最后展示效果如下

其它組件實(shí)現(xiàn)方法基本一致，這里就不再一一實(shí)現(xiàn)了，接下來(lái)就是將我們的組件庫(kù)文檔部署到github的靜態(tài)服務(wù)上了

部署到GitHub Pages

既然要部署到GitHub Pages，你得先在github新建一個(gè)倉(cāng)庫(kù)，因?yàn)橐盟腉itHub Pages，所以倉(cāng)庫(kù)命名為username.github.io的形式，username是你github的用戶(hù)名。然后點(diǎn)擊設(shè)置

選擇pages

這里設(shè)置根目錄/(root),當(dāng)然也可以選擇其它目錄,點(diǎn)擊保存，如果選擇其它目錄比如docs，config.js就需要配置一個(gè)base

export default {
    base:'/docs/'
  }

最后選擇一個(gè)主題(這里不選擇我發(fā)現(xiàn)站點(diǎn)不生效,后面把打包后的代碼推上來(lái)即可,會(huì)默認(rèn)加載index.html)

然后將打包后的dist下的文件推送到你的遠(yuǎn)程倉(cāng)庫(kù)。vitepress官網(wǎng)給我們提供了一個(gè)腳本文件deploy.sh,我們只需要改下遠(yuǎn)程倉(cāng)庫(kù)即可

#!/usr/bin/env sh
# 忽略錯(cuò)誤
set -e
# 構(gòu)建
npm run docs:build
# 進(jìn)入待發(fā)布的目錄
cd docs/.vitepress/dist
# 如果是發(fā)布到自定義域名
# echo 'www.example.com' > CNAME
git init
git add -A
git commit -m 'deploy'
# 如果部署到 https://<USERNAME>.github.io
# git push -f git@github.com:<USERNAME>/<USERNAME>.github.io.git master
# 如果是部署到 https://<USERNAME>.github.io/<REPO>
# git push -f git@github.com:<USERNAME>/<REPO>.git master:gh-pages
cd -

直接執(zhí)行這個(gè)腳本文件，我們的打包后的文件就會(huì)被推送到我們的倉(cāng)庫(kù)。然后我們就可以直接訪問(wèn)我們的文檔站點(diǎn)了.如果你想要自定義其它域名的話(huà),可以創(chuàng)建一個(gè)組織然后在組織下新建倉(cāng)庫(kù)名為organization.github.io的形式(organization是你組織名)然后執(zhí)行同樣的操作即可。具體可以點(diǎn)這里創(chuàng)建 GitHub Pages 站點(diǎn)
最后代碼已經(jīng)推送到KittyUIDocs,需要的可以自行獲取

到此這篇關(guān)于使用VitePress搭建及部署vue組件庫(kù)文檔的文章就介紹到這了,更多相關(guān)VitePress 部署vue組件庫(kù)文檔內(nèi)容請(qǐng)搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持腳本之家！

您可能感興趣的文章: