使用 VuePress 搭建项目文档并部署到 GitHub Pages

使用 VuePress 搭建项目文档平台并部署到 GitHub Pages

前言

本文记录了使用 VuePress 2.x 搭建项目文档网站，并将其部署到 GitHub Pages 的完整过程。通过这个过程，我帮我们的项目实训完成了一个技术文档站点。

一、项目初始化

1.1 创建项目

# 创建项目目录
mkdir dramaReaderAi
cd dramaReaderAi

# 初始化 package.json
npm init

# 安装 VuePress 依赖
npm install -D vuepress@next @vuepress/client@next vue

1.2 配置基本脚本

在 package.json 中添加必要的脚本：

{
  "scripts": {
    "docs:dev": "vuepress dev docs",
    "docs:build": "vuepress build docs",
    "docs:clean-dev": "vuepress dev docs --clean-cache"
  }
}

二、项目结构搭建

2.1 创建必要的目录结构

# 创建文档目录结构
mkdir -p docs/.vuepress
mkdir -p docs/intro/{tech,features}
mkdir -p docs/tech/{frontend,backend,ai,knowledge-graph}
mkdir -p docs/roadmap
mkdir -p docs/about
mkdir -p docs/.vuepress/public/images

2.2 配置文件设置

在 docs/.vuepress/config.js 中配置网站：

import { defaultTheme } from '@vuepress/theme-default'
import { defineUserConfig } from 'vuepress/cli'
import { viteBundler } from '@vuepress/bundler-vite'

export default defineUserConfig({
  lang: 'zh-CN',
  title: '剧想·智读',
  description: 'AI驱动的沉浸式阅读与学习平台',
  // ... 其他配置
})

三、内容编写

3.1 首页设置

创建 docs/README.md 作为首页：

---
home: true
heroImage: /images/logo.png
heroText: 剧想·智读
tagline: AI驱动的沉浸式阅读与学习平台
actions:
  - text: 项目介绍
    link: /intro/
    type: primary
features:
  - title: AI驱动
    details: 利用大语言模型和知识图谱技术...
  # ... 其他特性
---

3.2 文档结构

• 项目介绍 (docs/intro/)
• 技术文档 (docs/tech/)
• 开发计划 (docs/roadmap/)
• 关于我们 (docs/about/)

四、部署到 GitHub Pages

4.1 创建 GitHub 仓库

1. 在 GitHub 上创建新仓库
   

2. 初始化本地仓库并推送代码：

git init
git add .
git commit -m "Initial commit"
git remote add origin https://github.com/用户名/dramaReaderAi.git
git push -u origin main

4.2 配置 GitHub Actions

创建 .github/workflows/deploy-docs.yml 文件：

name: Deploy VuePress site to Pages

on:
  push:
    branches: [main]
  workflow_dispatch:

# ... 完整的工作流配置

4.3 配置部署设置

1. 修改 VuePress 配置，添加 base 路径：

export default defineUserConfig({
  base: '/dramaReaderAi/',
  // ... 其他配置
})

2. 在 GitHub 仓库设置中启用 GitHub Pages
   • Settings > Pages
   • 选择 GitHub Actions 作为部署源

五、优化与问题解决

5.1 图标配置

配置网站图标和 favicon：

head: [
  ['link', { rel: 'icon', type: 'image/x-icon', href: '/dramaReaderAi/images/favicon.ico' }],
  // ... 其他图标配置
]

5.2 常见问题解决

1. 图片路径问题

   • 确保图片放在 docs/.vuepress/public/images 目录
   • 使用正确的路径引用图片

2. 部署问题

   • 检查 base 路径配置
   • 确保 GitHub Actions 权限正确
   • 验证工作流文件配置

[在这里添加问题解决过程的相关截图]

六、最终效果

项目成功部署在 GitHub Pages 上，可以通过 https://用户名.github.io/dramaReaderAi/ 访问。

总结

通过这个过程：

1. 搭建了一个基于 VuePress 2.x 的文档网站
2. 实现了完整的文档结构和导航
3. 配置了自动化部署流程
4. 解决了各种配置和部署问题

这个文档网站为项目提供了一个文档展示平台，为项目的后续开发和维护提供了重要的参考。

参考资料

1. VuePress 官方文档
2. GitHub Pages 文档
3. GitHub Actions 文档