快捷導(dǎo)航

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

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

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

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

安裝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"
  }

安裝組件庫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則是組件庫文檔的首頁
gulild放我們組件指南文檔

文檔首頁

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

---
layout: home

title: Kitty
titleTemplate: 一個Vue3組件庫

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

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

然后pnpm run docs:dev啟動我們的項目，我們就可以看到這樣的畫面

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

配置

導(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" }],
  },
}

我們在config.js中配置我們的logo、導(dǎo)航欄以及社交鏈接。此時我們的導(dǎo)航欄便配置完成

側(cè)邊欄

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

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

同時我們在guild目錄下新建installation.md和quickstart.md文件。接下來分別在這兩個文件中介紹我們組件庫的安裝以及使用（這里將Element Plus當(dāng)作我們自己的組件KittyUI）

installation.md

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

quickstart.md

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

這時候我們文檔的效果如下

接下來我們對組件的側(cè)邊欄做一個配置,和指南一樣，我們只需要在sidebar下再加個/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做一個演示，在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>

此時我們頁面即可展示我們的Button按鈕

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

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

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

部署到GitHub Pages

既然要部署到GitHub Pages，你得先在github新建一個倉庫，因為要用他的GitHub Pages，所以倉庫命名為username.github.io的形式，username是你github的用戶名。然后點擊設(shè)置

選擇pages

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

export default {
    base:'/docs/'
  }

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

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

#!/usr/bin/env sh
# 忽略錯誤
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í)行這個腳本文件，我們的打包后的文件就會被推送到我們的倉庫。然后我們就可以直接訪問我們的文檔站點了.如果你想要自定義其它域名的話,可以創(chuàng)建一個組織然后在組織下新建倉庫名為organization.github.io的形式(organization是你組織名)然后執(zhí)行同樣的操作即可。具體可以點這里創(chuàng)建 GitHub Pages 站點
最后代碼已經(jīng)推送到KittyUIDocs,需要的可以自行獲取

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

您可能感興趣的文章: