记录从0到1创建 VuePress 项目、并部署到 GitHub Pages 的详细步骤
推荐多使用 VuePress 中文文档

VuePress

安装

安装过程可以按照官方文档快速上手选项卡中的步骤来，须注意下 Node.js 的版本。本文使用的版本为： Vue Press 1.x、Node.js 14.18.0

  • Vue Press 1.x 需要 Node.js >= 8.6
  • Vue Press 2.x 需要 Node.js >= 14.18.0

配置

参考官方文档目录结构和基本配置选项卡。

vuepress自定义目录_前端

  • config.js：必要的配置文件，可以配置网站的导航栏，侧边栏，网站主题等信息。
module.exports = {
  title: 'Cleaner',  // 网站标题
  description: '个人网站',
  head: [ // 注入到当前页面的 HTML <head> 中的标签
    ['link', { rel: 'icon', href: '/logo.jpg' }], // 增加一个自定义的 favicon(网页标签的图标)
  ],
  base: '/', // 部署到GitHub Pages时会用到
  themeConfig: {
    nav:[ // 导航栏配置
    	{
        text: 'java',
        link: '/java/', 
        items: [
          {text: 'JVM', link: '/'},
          {text: '并发编程', link: '/'}
        ]
      },
      {text: '杂项', link: '/other/'},
      {text: '书籍', link: '/books/'}      
    ]}
};
  • public：存放静态资源，比如图片。
  • README.md（docs 目录下）：配置网站的首页布局。
home: true
title: 首页
author: Cleaner
data: '2022-8-30'
heroImage: /logo.jpg
heroText: null
tagline: null
actionText: 快速上手 →
actionLink: /
features:
- title: 简洁至上
  details: 以 Markdown 为中心的项目结构，以最少的配置帮助你专注于写作。
- title: Vue驱动
  details: 享受 Vue + webpack 的开发体验，在 Markdown 中使用 Vue 组件，同时可以使用 Vue 来开发自定义主题。
- title: 高性能
  details: VuePress 为每个页面预渲染生成静态的 HTML，同时在页面被加载的时候，将作为 SPA 运行。
footer: MIT Licensed | Copyright © 2018-present Evan You
  • deploy.sh：脚本文件，用来将项目部署到 GitHub Pages。参考官方文档部署选项卡。
#!/usr/bin/env sh

# 确保脚本抛出遇到的错误
set -e

# 生成静态文件
npm run build

# 进入生成的文件夹
cd docs/.vuepress/dist

# 如果是发布到自定义域名
# echo 'www.yourwebsite.com' > CNAME

git init
git add -A
git commit -m 'deploy'

# 如果你想要部署到 https://USERNAME.github.io
git push -f 仓库地址 分支  // 修改成自己的GitHub仓库地址和分支

cd -

运行

执行命令npm run docs:dev运行项目。访问 localhost:8080，界面展示如下。至此本地搭建 VuePress 项目成功。

vuepress自定义目录_github_02

GitHub Pages

新建仓库

登录 GitHub，新建一个仓库，仓库名称为 xxx.github.io，xxx 为你的 GitHub 账号名。这种仓库命名，之后部署到 GitHub Pages 后，通过仓库名称（例如：https://songjian-99.github.io/）就可以访问到网站。如果是其他的仓库名称，那么访问的域名就是 https://songjian-99.github.io/xxx，xxx 为你的仓库名，访问域名会自动加上中间的一层路径。（config.js 文件中的 base 属性也要对应上）

部署

执行deploy.sh脚本文件。执行成功后，进入 GitHub 仓库，可以看见我们代码已经 push上来了。注意修改脚本文件中的仓库地址。Windows 系统需要借助 git bash 窗口执行该脚本文件。

设置 Pages

  1. 进入代码仓库，选择 Settings。

vuepress自定义目录_Vue_03


2. 进入仓库设置界面。选择 Pages 选项卡。

vuepress自定义目录_Vue_04


3. 在 Build and deployment 下选择分支，点击 save 即可

vuepress自定义目录_vuepress自定义目录_05


至此项目部署成功，可以通过浏览器访问验证。

问题

  1. Vue Press 不会热更新，每次修改代码后都需要重新启动。
    解决：将package.json文件中运行项目的命令改为"docs:dev": "vuepress dev docs --temp .temp"。后面的--temp .temp使项目中文件修改后不用重新启动，达到热更新的效果。