vitepresss+github actions搭建和部署组件库文档

一.github创建一个仓库，我这里命名 vitedemo

二、配置vitepress

创建文件夹，也叫vitedemo

初始化项目

进入文件夹执行 npm init

安装依赖

    npm i --dev vitepress vue

在package.json中加入执行脚本

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

安装elementplus

npm i element-plus -S

目录结构

创建docs文件夹

在项目根目录下创建docs文件夹,并在docs下创建index.md，这个就是我们文档的首页

 //  index.md
 
 ---
layout: home

title: dlx-ui
titleTemplate: 一个Vue3组件库

hero:
  name: dlx-ui
  text: 一个Vue3组件库
  tagline: 自己学习用，仅供参考
  image:
    src: /logo.png
    alt: dlx-ui
  actions:
    - theme: brand
      text: 开始
      link: /guide/
    - theme: alt
      text: 在 Gitee 上查看
      link: https://gitee.com/chen_pengchao/dlx-ui

features:
  - icon: 💡
    title: Vue3组件库
    details: 基于vite5.x打包和TypeScript开发
  - icon: 📦
    title: 仅供学习使用
    details: Vue3组件库开发学习，请勿用于实际生产项目
  - icon: 🛠️
    title: 按需引入
    details: 直接支持按需引入无需配置任何插件。
---

配置vitepress

在docs下创建.vitepress,在.vitepress下创建config.js，

文件结构

.
├─ .github // 部署相关
│  ├─ workflows
│  │  ├─ deploy.yml
├─ docs
│  ├─ .vitepress
│  │  ├─ config.js // 打包配置的文件
│  ├─ index.md  // 首页
│  
└─ package.json

配置文件

具体配置请到vitepress官方网站查看

// docs/.vitepress/config.js
export default {
  base: '/vitedemo/',   // 注意这里一定不能配置错，否则会404
  themeConfig: {
    siteTitle: 'DLX UI',
    nav: [
      { text: '指南', link: '/guide/installation' },
      { text: '组件', link: '/components/button' },
    ],
    // 侧边栏
    sidebar: {
      '/guide/': [
        {
          items: [
            { text: '安装', link: '/guide/installation' },
            { text: '快速开始', link: '/guide/quickstart' },
          ],
        },
      ],
      '/components/': [
        {
          items: [
            { text: '按钮', link: '/components/button/' },
            { text: '标签', link: '/components/tag/' },
          ],
        },
      ],
    },
    socialLinks: [
      { icon: 'github', link: 'https://gitee.com/chen_pengchao/dlx-ui' },
    ],
  },
}

自定义主题

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

// docs/.vitepress/theme/index.js
import DefaultTheme from 'vitepress/theme'
import elementPlus from 'element-plus'
import 'element-plus/dist/index.css'  // 记得引入css
export default {
  ...DefaultTheme,
  enhanceApp: async ({ app }) => {
    // app is the Vue 3 app instance from `createApp()`. router is VitePress'
    // custom router. `siteData`` is a `ref`` of current site-level metadata.
    app.use(elementPlus)
  },
}

运行项目

npm run docs:dev

运行后打开页面如下

指南和组件

在docs新建components和guide文件夹分别存储我们的组件和指南相关内容。

跳转路径已经在config.js中配置好了，当点击指南按钮时，会跳转到/guide/installation

//  guide/installation.md
# 这是安装指南的内容

<!-- 安装指南 -->

## 安装

```bash
npm install dlx-ui

当点击组件按钮时，跳转组件页面

部署github

初始化本地仓库

git init

添加gitignore

node_modules
.DS_Store
dist
dist-ssr
cache
.cache
.temp
*.local

推送到远程仓库

 git add .
 
 git commit -m 'first commit'
 
git branch -M main
 
 git push -u origin main

自动部署

github设置actions

找到项目的settings下面的pages

添加deploy.yml文件

在项目的根目录下创建.github/workflows/deploy.yml

# 构建 VitePress 站点并将其部署到 GitHub Pages 的示例工作流程
#
name: Deploy VitePress site to Pages

on:
  # 在针对 `main` 分支的推送上运行。如果你
  # 使用 `master` 分支作为默认分支，请将其更改为 `master`
  push:
    branches: [main]

  # 允许你从 Actions 选项卡手动运行此工作流程
  workflow_dispatch:

# 设置 GITHUB_TOKEN 的权限，以允许部署到 GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write

# 只允许同时进行一次部署，跳过正在运行和最新队列之间的运行队列
# 但是，不要取消正在进行的运行，因为我们希望允许这些生产部署完成
concurrency:
  group: pages
  cancel-in-progress: false

jobs:
  # 构建工作
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0 # 如果未启用 lastUpdated，则不需要
      # - uses: pnpm/action-setup@v3 # 如果使用 pnpm，请取消此区域注释
      #   with:
      #     version: 9
      # - uses: oven-sh/setup-bun@v1 # 如果使用 Bun，请取消注释
      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: 18
          cache: npm # 或 pnpm / yarn
      - name: Setup Pages
        uses: actions/configure-pages@v4
      - name: Install dependencies
        run: npm ci # 或 pnpm install / yarn install / bun install
      - name: Build with VitePress
        run: npm run docs:build # 或 pnpm docs:build / yarn docs:build / bun run docs:build
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: docs/.vitepress/dist

  # 部署工作
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    needs: build
    runs-on: ubuntu-latest
    name: Deploy
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

上面的代码可以直接复制使用，需要注意的是分支是master还是你自己定义的，修改一下即可。

最后

当修改文件，推送到github的main分支后，github会自动执行action

当构建成功，会是绿色按钮，点击绿色按钮，会有文档访问地址，浏览器输入地址即可访问。

全部代码都这这里了：源码地址