搭建自己的文档网站：VuePress+ThemeHope保姆级指南

介绍：

VuePress

官网: Home | VuePress(官网)

• 基于 Vue.js 的静态网站生成器
• 专为技术文档、博客和知识库设计
• 结合 Markdown 的易用性与 Vue 的强大功能
• 快速创建专业网站，高度可定制

Theme Hope

官网: 主页 | vuepress-theme-hope(官网)

• VuePress 2 的专业增强主题
• 专为文档和博客设计
• 效果预览: 真实项目 | vuepress-theme-hope

GitHub Pages

官网: GitHub Pages(官网)

• GitHub 提供的静态网站托管服务
• 完全免费，直接与 GitHub 仓库集成
• 支持自定义域名，自动 HTTPS 加密
• 主要用途:
  • 个人/项目展示页
  • 技术文档托管
  • 博客网站
  • 项目演示页

效果预览：[真实项目 | vuepress-theme-hope](

环境准备

需要工具清单：

1. 一台能上网的电脑（Windows/Mac都行）
2. 安装Node.js（点击这里下载）
3. 代码编辑器推荐VSCode（免费好用）

避坑指南：
Windows小伙伴注意！安装Node.js时务必勾选"Add to PATH"选项
安装完成后打开CMD输入：

node -v  # 应该显示v18.x或更高
npm -v   # 应该显示9.x或更高

如果报错，请重启电脑后再试

---

项目创建

第1步：创建你的知识库

# 在桌面创建项目文件夹（可自定义位置）
mkdir my-knowledge && cd my-knowledge   //这里的my-knowledge就是你的文件夹名字，可自定义

建议路径不要有中文和空格，避免奇怪报错

第2步：初始化项目

npm init -y  # 生成package.json文件

重要说明：
这个文件相当于项目的身份证，记录所有依赖和配置，后续操作都在此基础上进行

第3步：安装全家桶

npm install -D vuepress@2 vuepress-theme-hope @vuepress/bundler-vite sass-embedded

为什么装这么多？

• @vuepress/bundler-vite：新版必需打包工具
• sass-embedded：防止样式编译报错
• vuepress-theme-hope：超强主题插件库

---

文件结构搭建

my-knowledge/
├── docs/                # 核心文档目录
│   ├── .vuepress/       # 配置目录
│   │   ├── styles/      # 自定义样式
│   │   │   └── index.scss
│   │   └── config.js    # 核心配置文件
│   ├── java/            # 分类目录示例
│   │   ├── 基础语法.md
│   │   └── 面向对象.md
│   └── README.md        # 首页
└── package.json         # 项目配置

右键新建文件夹时记得显示隐藏文件，才能看到.vuepress目录

---

配置文件详解

docs/.vuepress/config.js

作为 VuePress 文档站的核心配置文件，config.js 承担了全局配置、主题定制、功能扩展等关键功能。

主要分为五个方面：基础站点配置，主题与布局控制，插件与功能扩展，样式与交互定制，构建与部署优化

import { hopeTheme } from "vuepress-theme-hope";
import { viteBundler } from "@vuepress/bundler-vite";

// 新手注意！以下配置直接复制修改即可
export default {
  bundler: viteBundler(), // 必须配置
  
  // 基础设置
  title: "我的知识库",     // 网站标题
  description: "每天进步一点点", // SEO描述
  
  // 主题配置
  theme: hopeTheme({
    repo: "你的GitHub账号/仓库名", // 后续部署用
    docsDir: "docs",             // 文档目录
    
    // 导航栏配置（可添加图标）
    navbar: [
      { 
        text: " 首页", 
        link: "/",
        icon: "home" 
      },
      {
        text: " Java教程",
        link: "/java/",
        icon: "java"
      }
    ],
    
    // 智能侧边栏（自动识别目录结构）
    sidebar: "structure",
    
    // 增强功能（按需开启）
    plugins: {
      copyCode: true,       // 代码复制按钮
      photoSwipe: true,     // 图片放大查看
      mdEnhance: {
        tasklist: true,     // 待办清单
        mark: true          // 荧光笔效果
      }
    }
  })
}

小技巧：图标列表可在theme-hope官网查找

---

个性化定制

字体优化方案

在.vuepress/styles/index.scss（如果没有这个文件要自己创建，名字和文件后缀必须一模一样）中添加：

// 中文字体优化方案
body {
  font-family: "HarmonyOS Sans", "PingFang SC", sans-serif;
  font-size: 18px;
  line-height: 1.8;
  
  h1 { color: #2c3e50; } // 标题颜色
  a { color: #3eaf7c; }  // 链接颜色
}

推荐使用思源黑体更专业

导航栏美化

.navbar {
  background: linear-gradient(45deg, #3eaf7c, #2c3e50);
  box-shadow: 0 2px 8px rgba(0,0,0,0.1);
  
  .nav-item {
    transition: transform 0.3s;
    &:hover {
      transform: translateY(-2px);
    }
  }
}

这是我个人使用的：

可自行选择更改，也可以直接ctrl + a + c + v

/* ============================
   全局字体和布局设置
   ============================ */

/* 使用 Google 字体 */
@import url("https://fonts.googleapis.com/css2?family=Noto+Sans+SC:wght@400;500;700&family=Noto+Serif+SC:wght@400;500&display=swap");

/* 全局字体和行高 */
body {
  font-family: "Noto Serif SC", serif !important;  /* 采用衬线字体 */
  font-size: 20px !important;  /* 字体较大 */
  line-height: 1.8 !important; /* 增加行高 */
  color: #333 !important;  /* 深灰色文字 */
  background-color: #f5f5f5 !important; /* 背景色 */
}

/* ============================
   顶部导航栏布局调整
   ============================ */

/* 顶部导航栏 */
.navbar {
  height: 100px !important;   /* 顶部导航栏高度 */
  background-color: #333 !important;  /* 背景色 */
  display: flex;
  align-items: center;        /* 垂直居中 */
  padding: 0 2rem;            /* 增加左右内边距 */
  box-sizing: border-box;
}

/* 顶部导航栏项 */
.navbar .navbar-items .nav-item {
  font-family: "Noto Sans SC", sans-serif !important;  /* 无衬线字体 */
  font-size: 22px !important;  /* 字体更大 */
  padding: 0 1.5rem !important;  /* 增加左右内边距 */
  color: #fff !important;      /* 白色字体 */
  font-weight: 500 !important;
  transition: color 0.3s ease;
}

/* 鼠标悬停时的字体颜色 */
.navbar .navbar-items .nav-item:hover {
  color: #ff9f00 !important;  /* 悬停时字体颜色变亮 */
}

/* ============================
   左侧边栏布局调整
   ============================ */

/* 左侧边栏容器 */
.sidebar {
  width: 300px !important;  /* 侧边栏宽度调整 */
  background-color: #f4f4f4 !important;  /* 背景色 */
  padding-top: 1.5rem;      /* 顶部留白 */
  padding-left: 1.8rem;     /* 左侧内边距增大 */
  padding-right: 1.8rem;    /* 右侧内边距增大 */
  box-sizing: border-box;
}

/* 侧边栏标题（一级目录） */
.sidebar .sidebar-heading {
  font-family: "Noto Sans SC", sans-serif !important;
  font-size: 22px !important;  /* 增加侧边栏标题的字体大小 */
  font-weight: 700 !important; /* 加粗，突出目录 */
  padding: 0.5rem 0 !important;
  margin: 1.5rem 0 !important;
  color: #2c3e50 !important;
}

/* 侧边栏链接（导航项） */
.sidebar .sidebar-item {
  font-family: "Noto Sans SC", sans-serif !important;
  font-size: 18px !important;  /* 增大字体 */
  font-weight: 400 !important;
  padding: 1rem 2rem !important;  /* 增加内边距 */
  margin-bottom: 1rem;   /* 增加每个项目之间的间距 */
  color: #34495e !important;   /* 深灰色文字 */
  transition: background-color 0.3s ease, color 0.3s ease;
}

/* 侧边栏项目悬停效果 */
.sidebar .sidebar-item:hover {
  background-color: #e0e0e0 !important;  /* 背景颜色变化 */
  color: #ff9f00 !important;             /* 字体颜色变亮 */
}

/* ============================
   右侧边栏布局调整（如果有右侧边栏）
   ============================ */

/* 右侧边栏容器 */
.sidebar-right {
  width: 300px !important;  /* 右侧边栏宽度调整 */
  background-color: #f4f4f4 !important;  /* 背景色 */
  padding-top: 1.5rem;      /* 顶部留白 */
  padding-left: 1.8rem;     /* 左侧内边距增大 */
  padding-right: 1.8rem;    /* 右侧内边距增大 */
  box-sizing: border-box;
}

/* 右侧边栏标题 */
.sidebar-right .sidebar-heading {
  font-family: "Noto Sans SC", sans-serif !important;
  font-size: 22px !important;
  font-weight: 700 !important;
  color: #2c3e50 !important;
}

/* 右侧边栏链接（导航项） */
.sidebar-right .sidebar-item {
  font-family: "Noto Sans SC", sans-serif !important;
  font-size: 18px !important;  /* 字体增大 */
  padding: 1rem 2rem !important;
  margin-bottom: 1rem;
  color: #34495e !important;
}

.sidebar-right .sidebar-item:hover {
  background-color: #e0e0e0 !important;
  color: #ff9f00 !important;
}

/* ============================
   正文部分布局调整
   ============================ */

/* 正文内容 */
.theme-hope-content {
  font-family: "Noto Serif SC", serif !important; /* 使用衬线字体 */
  font-size: 20px !important;   /* 字体大小 */
  line-height: 1.9 !important;  /* 增加行高 */
  color: #2c3e50 !important;   /* 深色字体 */
  max-width: 1200px !important; /* 页面最大宽度 */
  margin: 2rem auto;            /* 页面内容居中 */
}

/* 正文标题 */
.theme-hope-content h1 {
  font-size: 36px !important;  /* 一级标题字体更大 */
  font-weight: 700 !important; /* 加粗 */
  font-family: "Noto Sans SC", sans-serif !important;
}

.theme-hope-content h2 {
  font-size: 28px !important;  /* 二级标题 */
  font-weight: 600 !important;
}

.theme-hope-content h3 {
  font-size: 24px !important;  /* 三级标题 */
  font-weight: 500 !important;
}

/* ============================
   其他小细节
   ============================ */

/* 设置链接的颜色 */
a {
  color: #2980b9 !important;   /* 蓝色链接 */
  text-decoration: none !important;  /* 去除下划线 */
}

a:hover {
  color: #ff9f00 !important;  /* 链接悬停时改变颜色 */
}

---

部署到Github Pages

手动部署

1.关键配置

修改 docs/.vuepress/config.js，添加：

export default {
  base: "/仓库名/", // 非个人主页仓库必加[4,8](@ref)
  // 其他配置不变
}

2.打包构建

npm run build  # 生成静态文件到 docs/.vuepress/dist

3.手动部署

cd docs/.vuepress/dist
git init
git add .
git commit -m "手动部署"
git branch -M gh-pages
git remote add origin https://github.com/你的账号/仓库名.git
git push -f origin gh-pages

4. GitHub 设置

1. 进入仓库 Settings → Pages
2. 选择 gh-pages 分支
3. 选择 /(root) 目录
4. 保存后访问：https://用户名.github.io/仓库名/

关键说明

1,所有操作均在 dist 目录下完成

2,必须保证 base 配置与仓库名一致（区分大小写）

3,更新内容需重新执行 npm run build 和推送步骤

自动部署(监听 Git 推送事件 并触发构建流程)

1. 创建部署配置文件

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

name: Deploy
on: [push]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm install
      - run: npm run build
      - name: Deploy
        uses: JamesIves/github-pages-deploy-action@v4
        with:
          branch: gh-pages
          folder: docs/.vuepress/dist

2. 生成访问令牌（Token）

1. 访问 GitHub Token 生成页面
2. 勾选 repo 权限
3. 复制生成的 Token（仅显示一次）

3. 配置仓库密钥

1. 进入仓库 Settings → Secrets → Actions
2. 新建密钥 ACTIONS_DEPLOY_KEY，粘贴刚才的 Token

4. 触发自动部署

推送代码到主分支后

git add .
git commit -m "触发自动部署"
git push

5. 查看结果

1. 仓库 Actions 标签页查看构建状态
2. 仓库 Settings → Pages 确认 gh-pages 分支已启用

常见问题

1. 启动时报错 No bundler detected

解决方案：

npm install -D @vuepress/bundler-vite

并在config.js添加bundler: viteBundler()

2. 样式编译失败 sass-embedded not found

必装依赖：

npm install -D sass-embedded

这是新版VuePress的强制要求

3. GitHub Pages部署后样式丢失

检查config.js是否配置base路径：

module.exports = {
  base: "/仓库名/", // 例如 "/my-docs/"
}

详见部署章节

---

一键部署脚本

创建deploy.sh文件：

#!/bin/bash

# 清除旧构建
rm -rf docs/.vuepress/dist

# 全新构建
npm run build

# 进入构建目录
cd docs/.vuepress/dist

# 自动提交
git init
git add -A
git commit -m "docs: 自动部署 $(date '+%Y-%m-%d %H:%M:%S')"
git branch -M gh-pages
git remote add origin https://github.com/你的账号/仓库名.git
git push -f origin gh-pages

echo "✅ 部署成功！访问地址：https://你的账号.github.io/仓库名/"

运行方式：

chmod +x deploy.sh  # 添加执行权限
./deploy.sh         # 一键部署

---

高级技巧

1. SEO优化：在frontmatter添加关键词

---
title: Java面向对象编程
keywords: [Java, OOP, 封装继承多态]
---

1. 文档版本控制：

/docs
  ├── v1.0/
  └── v2.0/

通过navbar配置版本切换

1. 数据统计：在config.js添加：

plugins: [
  ['@vuepress/google-analytics', { ga: 'UA-XXXXX-X' }]
]