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

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

安装插件

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

sql 复制代码

# 安装 VuePress 和 Vue
pnpm add -D vuepress@next vue

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

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

项目结构

完整项目结构应如下

md 复制代码

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

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

核心配置文件

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

typescript 复制代码

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.md
    navbar: [
      { 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 中添加以下脚本命令：

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 脚本示例：

bash 复制代码

#!/usr/bin/env sh

# 确保脚本遇到错误时退出
set -e

push_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_path

git init
git add -A
git commit -m "deploy, $commit_info"
git push -f $push_addr HEAD:$push_branch

cd -
rm -rf $dist_path

此脚本的主要步骤包括：

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

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

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 的文档站点的搭建

📚 结语

通过 VuePress，我们可以在项目中轻松集成说明文档、技术笔记或产品手册，并可一键部署至 GitHub Pages，方便他人访问与协作，免去繁琐的前后端搭建过程。

这种方式不仅有助于提升用户上手效率、降低学习成本，也能显著增强产品的专业性与文档质量。如果你也有类似需求，非常推荐尝试 VuePress 这个轻量、灵活、易上手的文档解决方案。

👉 官方 GitHub 地址：VuePress 仓库

如果你觉得这篇文章对你有帮助，欢迎点赞、收藏或留言交流 😊