怎么使用VitePress搭建及部署vue組件庫文檔

這篇文章主要介紹了怎么使用VitePress搭建及部署vue組件庫文檔的相關(guān)知識，內(nèi)容詳細(xì)易懂，操作簡單快捷，具有一定借鑒價(jià)值，相信大家閱讀完這篇怎么使用VitePress搭建及部署vue組件庫文檔文章都會有所收獲，下面我們一起來看看吧。

安裝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)的樣式給我們組件庫整個(gè)首頁，在index.md文件中寫入

---
layout: home

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

hero:
  name: Kitty
  text: 一個(gè)Vue3組件庫
  tagline: 沒啥特點(diǎn)僅供學(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í)，請勿用于實(shí)際生產(chǎn)項(xiàng)目
  - icon: ?????
    title: 按需引入
    details: 直接支持按需引入無需配置任何插件。
---

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

是不是感覺已經(jīng)有點(diǎn)組件庫文檔的意思了。接下來對導(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" }],
  },
}

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

側(cè)邊欄

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

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

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

installation.md

# 安裝
## 環(huán)境支持
由于 Vue 3 不再支持 IE11，KittyUI 也不再支持 IE11 瀏覽器。
## 版本
Element Plus 目前還在開發(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

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

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

接下來我們對組件的側(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í)我們頁面即可展示我們的Button按鈕

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

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

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

部署到GitHub Pages

既然要部署到GitHub Pages，你得先在github新建一個(gè)倉庫，因?yàn)橐盟腉itHub Pages，所以倉庫命名為username.github.io的形式，username是你github的用戶名。然后點(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)不生效,后面把打包后的代碼推上來即可,會默認(rèn)加載index.html)

然后將打包后的dist下的文件推送到你的遠(yuǎn)程倉庫。vitepress官網(wǎng)給我們提供了一個(gè)腳本文件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í)行這個(gè)腳本文件，我們的打包后的文件就會被推送到我們的倉庫。然后我們就可以直接訪問我們的文檔站點(diǎn)了.如果你想要自定義其它域名的話,可以創(chuàng)建一個(gè)組織然后在組織下新建倉庫名為organization.github.io的形式(organization是你組織名)然后執(zhí)行同樣的操作即可。

關(guān)于“怎么使用VitePress搭建及部署vue組件庫文檔”這篇文章的內(nèi)容就介紹到這里，感謝各位的閱讀！相信大家對“怎么使用VitePress搭建及部署vue組件庫文檔”知識都有一定的了解，大家如果還想學(xué)習(xí)更多知識，歡迎關(guān)注億速云行業(yè)資訊頻道。