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

已于 2025-05-14 11:41:31 修改
阅读量1.9k 收藏 22
点赞数 56
文章标签： vue github 个人开发
于 2025-05-14 11:37:47 首次发布
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
本文链接：https://blog.csdn.net/2301_79902294/article/details/147950558
版权

介绍：

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' }]
]
nu11cat
关注
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值