当前位置：首页 > news >正文

使用 Vuepress + GitHub Pages 搭建项目文档

news 2025/8/4 12:45:52

VuePress 是一个基于 Vue.js 的静态网站生成器，常用于创建文档站点或个人博客。下面将介绍如何在已有的项目中进行搭建

安装插件

在项目中使用 pnpm 管理依赖，并安装 VuePress 本身以及必需的打包器和主题插件：

# 安装 VuePress 和 Vue
pnpm add -D vuepress@next vue# 安装打包器和默认主题
pnpm add -D @vuepress/bundler-vite@next @vuepress/theme-default@next

一般使用 pnpm workspace 管理项目，通常将文档目录命名为 docs。

项目结构

完整项目结构应如下

├─ docs
│  ├─ .vuepress
│  │  └─ config.js
│  └─ README.md
└─ package.json

README.md 为页面 md 文件，可自行定义路径

核心配置文件

VuePress 的核心配置文件位于 docs/.vuepress/config.js 或 config.ts。以下是一个示例配置：

import { viteBundler } from '@vuepress/bundler-vite'
import { defaultTheme } from '@vuepress/theme-default'
import { defineUserConfig } from 'vuepress'export default defineUserConfig({bundler: viteBundler(),theme: defaultTheme({// link 为 docs 目录下的绝对路径// 假设 docs/coding 下有个 html.md 文件// /coding/html.mdnavbar: [{ text: '首页', link: '/README.md' },{		text: '分页',children: [{ text: '分页章节1', link: '/coding/html.md' }],}],sidebar: [{text: '分页',children: [{text: '分页章节1',link: '/coding/html.md',}],}]}),lang: 'zh-CN',title: '测试项目',description: '',base: '/project-name/' // project-name 建议设置为当前项目名
})

这个配置文件中包含以下常用选项：

bundler: viteBundler()：指定使用 Vite 作为打包器。
theme: defaultTheme({...})：使用默认主题并自定义配置。
navbar：定义导航栏的内容，例如首页链接和带有子菜单的条目。
sidebar：定义侧边栏的结构，通常用于文档分类目录。
lang、title、description 等字段：设置站点的语言、标题和描述信息。
base：指定站点部署时的基础路径（如果文档不在根路径时需要配置）。

通过配置 navbar 和 sidebar，我们可以自定义网站的导航结构，使用户更容易浏览文档内容。

运行和构建脚本

在项目的 package.json 中添加以下脚本命令：

{"scripts": {"docs:dev": "vuepress dev docs","docs:build": "vuepress build docs"}
}

docs:dev：启动本地开发服务器，实时预览文档内容。
docs:build：构建生成静态文件。

可以使用命令 npm run docs:dev 来启动项目，npm run docs:build 来构建最终的静态站点文件。

部署到 GitHub Pages

下面是一段用于将生成的静态文件发布到 GitHub Pages 的 deploy.sh 脚本示例：

#!/usr/bin/env sh# 确保脚本遇到错误时退出
set -epush_addr=`git remote get-url --push origin`
commit_info=`git describe --all --always --long`
dist_path=docs/.vuepress/dist
push_branch=gh-pages# 生成静态文件
npm run docs:build# 进入生成的文件夹
cd $dist_pathgit init
git add -A
git commit -m "deploy, $commit_info"
git push -f $push_addr HEAD:$push_branchcd -
rm -rf $dist_path

此脚本的主要步骤包括：

使用 npm run docs:build 生成静态文件到 docs/.vuepress/dist。
初始化一个新的临时 Git 仓库，将生成的文件提交并强制推送到远程的 gh-pages 分支。
删除本地生成目录的副本。

在 package.json 中添加以下脚本命令以便执行部署：

{"scripts": {"deploy": "bash deploy.sh" // git bash 中使用"docs:build": "vuepress build docs"}
}

运行 npm run deploy 后，就会将文档部署到远程仓库的 gh-pages 分支。最后，在 GitHub 项目仓库的 Settings > Pages 中，将 Pages 的 Source 分支设置为 gh-pages，即可成功实现基于 VuePress 的文档站点的搭建