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

每個組件庫都有它們自己的文檔。所以當我們開發完成我們自己的組件庫必須也需要一個組件庫文檔。如果你還不了解如何搭建自己的組件庫可以看這裡->從零搭建Vue3組件庫。看完這篇文章你就會發現原來搭建和部署一個組件庫文檔是那麼的簡單。當然部署也不需要你有自己的伺服器，你只要有github即可。由於我們的組件庫還沒有完成，所以下面就以element-plus作為示例來搭建一個文檔吧。

安裝vitepress

首先新建文件夾就叫kittydocs,執行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

目錄結構

新建kittydocs目錄，其中文件結構如下圖

1659894261414.jpg

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

文檔首頁

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

---
layout: home

title: Kitty
titleTemplate: 一個Vue3組件庫

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

features:
  - icon: 💡
    title: Vue3組件庫
    details: 基於vite打包和TypeScript開發
  - icon: 📦
    title: 僅供學習使用
    details: 傾向於Vue3組件庫的學習，請勿用於實際生產項目
  - icon: 🛠️
    title: 按需引入
    details: 直接支援按需引入無需配置任何插件。
---

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

1659855496770.jpg

是不是感覺已經有點組件庫文檔的意思了。接下來對導航欄以及我們們文檔的側邊欄進行一個配置。

配置

導航欄配置

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

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

1659856636302.jpg

側邊欄

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

    sidebar: {
      "/guild/": [
        {
          text: "基礎",
          items: [
            {
              text: "安裝",
              link: "/guild/installation",
            },
            {
              text: "快速開始",
              link: "/guild/quickstart",
            },
          ],
        },
        {
          text: "進階",
          items: [
            {
              text: "xx",
              link: "/xx",
            },
          ],
        },
      ],
    },

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

  • installation.md
# 安裝

## 環境支援

由於 Vue 3 不再支援 IE11，KittyUI 也不再支援 IE11 瀏覽器。

## 版本

Element Plus 目前還在開發迭代中

## 使用包管理器

建議您使用包管理器 (NPM, Yarn, pnpm) 安裝 KittyUI, 然後您就可以使用打包工具，例如 Vite 和 webpack

# 選擇一個你喜歡的包管理器

# NPM
$ npm install kitty-ui --save

# Yarn
$ yarn add kitty-ui

# pnpm
$ pnpm install kitty-ui

## 瀏覽器直接引入

暫不支援
  • quickstart.md
# 快速開始

本節將介紹如何在項目中使用 KittyUI

## 用法

...
<template>
  <Button>按鈕</Button>
</template>

<script setup>
    import { Button } from 'kitty-ui'
</script>
...

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

1659858483511.jpg

接下來我們對組件的側邊欄做一個配置,和指南一樣，我們只需要在sidebar下再加個/examples/路徑即可

      "/examples/": [
        {
          text: "基礎組件",
          items: [
            {
              text: "Button按鈕",
              link: "/examples/button/",
            },
            {
              text: "Icon圖標",
              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>默認按鈕</el-button>
<br/><br/>
<el-button>默認按鈕</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按鈕

1659859259210.jpg

基於此，我們便可以輕鬆使用markdown文件的形式來編寫我們的組件使用文檔了。程式碼有點長，這裡就貼一部分程式碼展示與隱藏的實現部分

1660063541877.jpg

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

1659861626395.jpg

其它組件實現方法基本一致，這裡就不再一一實現了，接下來就是將我們的組件庫文檔部署到github的靜態服務上了

部署到GitHub Pages

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

1659636707491.jpg

選擇pages

1659667081306.png

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

export default {
    base:'/docs/'
  }

最後選擇一個主題(這裡不選擇我發現站點不生效,後面把打包後的程式碼推上來即可,會默認載入index.html)

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

#!/usr/bin/env sh

# 忽略錯誤
set -e

# 構建
npm run docs:build

# 進入待發布的目錄
cd docs/.vitepress/dist

# 如果是發布到自定義域名
# echo 'www.example.com' > CNAME

git init
git add -A
git commit -m 'deploy'

# 如果部署到 //<USERNAME>.github.io
# git push -f [email protected]:<USERNAME>/<USERNAME>.github.io.git master

# 如果是部署到 //<USERNAME>.github.io/<REPO>
# git push -f [email protected]:<USERNAME>/<REPO>.git master:gh-pages

cd -

直接執行這個腳本文件，我們的打包後的文件就會被推送到我們的倉庫。然後我們就可以直接訪問我們的文檔站點了.如果你想要自定義其它域名的話,可以創建一個組織然後在組織下新建倉庫名為organization.github.io的形式(organization是你組織名)然後執行同樣的操作即可。具體可以點這裡創建 GitHub Pages 站點
最後程式碼已經推送到KittyUIDocs,需要的可以自行獲取

創作不易，你的點贊就是我的動力！如果感覺這篇文章對你有幫助的話就請點個贊吧，謝謝謝！！

Tags:

VirMach 便宜 VPS

QNews

QNews