VuePress + Github Pages 搭建博客网站

VuePress

VuePress 是基于 Vue 的静态网站生成器，有以下特点：

• 简洁至上：以 Markdown 为中心的项目结构，以最少的配置帮助你专注于写作
• Vue 驱动：享受 Vue + webpack 的开发体验，可以在 Markdown 中使用 Vue 组件，又可以使用 Vue 来开发自定义主题
• 高性能：VuePress 会为每个页面预渲染生成静态的 HTML，同时，每个页面被加载的时候，将作为 SPA 运行

VuePress 中文文档 | VuePress 中文网 www.vuepress.cn/guide/

1. 创建 VuePress 网站

1. 创建并进入新目录

mkdir vuepress-starter && cd vuepress-starter

1. 使用包管理器初始化项目（npm 或 yarn）

npm init

或

yarn init

1. 将 VuePress 安装为本地依赖（不推荐全局安装 VuePress）

npm install -D vuepress

或

yarn add -D vuepress

1. 创建存放文档的目录 docs，并创建一篇文档

mkdir docs && echo '# Hello VuePress' > docs/README.md

README.md 相当于网站首页，可以使用 Markdown 语法编辑文档

1. 在 package.json 中添加 scripts(opens new window) 命令

{
  "scripts": {
    "docs:dev": "vuepress dev docs",
    "docs:build": "vuepress build docs"
  }
}

1. 启动本地服务器

npm run docs:dev

或

yarn docs:dev

VuePress 会在 http://localhost:8080 启动一个热重载的开发服务器

2. 配置文件

在文档目录 docs 下创建 .vuepress 目录，所有 VuePress 相关的文件都放在这里

目录结构：

在 .vuepress 目录下创建 VuePress 网站必要的配置文件 config.js，它应该导出一个 JavaScript 对象：

module.exports = {
  title: '廊坊吴彦祖', // 网站的标题，它将会被用作所有页面标题的前缀，同时，默认主题下，它将显示在导航栏（navbar）上。
  description: '廊坊吴彦祖的vuepress博客网站' // 网站的描述，它将会以 <meta> 标签渲染到当前页面的 HTML 中。
}

所有可选配置：www.vuepress.cn/config/#%E5…

对于上述的配置，如果你运行起 dev server，你应该能看到一个页面，它包含一个页头，里面包含一个标题和一个搜索框。VuePress 内置了基于 headers 的搜索 —— 它会自动为所有页面的标题、h2 和 h3 构建起一个简单的搜索索引

此时网站效果:

3. 导航栏和侧边栏

在配置文件 .vuepress/config.js 中增加主题配置字段 themeConfig

详细配置文档：www.vuepress.cn/theme/defau…

设置导航栏：

在 themeConfig 字段中增加导航栏配置字段 nav

详细配置文档：www.vuepress.cn/theme/defau…

此时网站效果:

设置侧边栏：

在 themeConfig 字段中增加导航栏配置字段 sidebar

详细配置文档：www.vuepress.cn/theme/defau…

创建博客对应页面的 Markdown 文档

目录结构：

此时网站效果:

4. 此时 VuePress 博客网站已经基本搭建完成

---

GitHub Pages

GitHub Pages 是通过 GitHub 托管和发布的公共网页

---

在 GitHub 上创建 Github Pages 站点

1. 新建项目仓库

在 GitHub（github.com）中点击右上角 + => New repository 创建网站项目仓库

输入 username.github.io 作为仓库名称（ username 为你的 GitHub 用户名。 例如，如果你的用户名是 xxxxxx，则仓库名称为 xxxxxx.github.io）

2. 查看 Github Pages

在创建的网站项目仓库中点击 setting

点击左侧 Pages，右侧 Github Pages 显示了站点网址 https://username.github.io/（该网址为博客网站的站点网址）

---

将 VuePress 网站部署到 Github Pages 站点

1. 将 VuePress 网站项目关联 GitHub 仓库

使用 git 命令初始化本地 vuepress-starter 项目（VuePress 网站），并将项目关联 GitHub 上新创建的 username.github.io 仓库

2. 在 config.js 中设置 base

在 docs/.vuepress/config.js 中设置正确的 base

• 如果你打算发布到 https://username.github.io/，则可以省略这一步，因为 base 默认即是 "/"（以上步骤使用此条）

• 如果你打算发布到 https://username.github.io/project/（也就是说你的仓库在 https:// github.com/username/project），则将 base 设置为 "/project/"（username 为你的 GitHub 用户名，project 为你的 项目）

3. 创建部署脚本 deploy.sh

在项目根目录下创建部署脚本 deploy.sh（请自行判断去掉对应的 1、2、3 条注释）

按照以上步骤项目将发布到 https://username.github.io/，所以去掉第 2 条的注释，并修改为对应的仓库地址

#!/usr/bin/env sh

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

# 生成静态文件
npm run docs:build

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

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

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

# 2、如果发布到 https://<USERNAME>.github.io
# git push -f git@github.com:<USERNAME>/<USERNAME>.github.io.git master

# 3、如果发布到 https://<USERNAME>.github.io/<REPO>
# git push -f git@github.com:<USERNAME>/<REPO>.git master:gh-pages

cd -

4. 执行部署脚本 deploy.sh

在 package.json 中添加 scripts 命令 deploy 来执行部署脚本 deploy.sh

{
  "scripts": {
    "docs:dev": "vuepress dev docs",
    "docs:build": "vuepress build docs",
    "deploy": "bash deploy.sh"
  }
}

执行 scripts 命令（之后每次增加/修改博客内容只需执行此命令便可完成网站部署）

npm run deploy

或

yarn deploy

此时 docs/.vuepress 目录下生成打包文件 dist

项目打包文件 dist 的内容被提交到 GitHub 仓库

5. VuePress 网站部署完成

此时 VuePress + Github Pages 搭建的博客网站已经部署完成 ，访问站点网址 https://username.github.io/ 便可访问