一篇带你用 VuePress + Github Pages 搭建博客

[mqyqingfeng]

前言

最近完成了 TypeScript 最新官方文档 Hanbook 的翻译，一共十四篇，堪称国内的最好 TypeScript4 入门教程之一。为了方便大家阅读，我用 VuePress + Github Pages 搭建了博客，博客效果如下：

博客地址如下：

• Github https://mqyqingfeng.github.io/learn-typescript/
• Gitee http://mqyqingfeng.gitee.io/learn-typescript/

0. VuePress

VuePress 自然不用多说，基于 Vue 的静态网站生成器，风格简约，配置也比较简单。之所以不使用 VitePress，是因为想使用现有的主题， 而 VitePress 不兼容当前 VuePress 的生态系统，至于为什么不选择 VuePress@next，考虑到还处于 Beta 阶段，等稳定后再开始迁移。

1. 本地搭建

快速开始同 VuePress 官网：

1. 创建并进入一个新目录

// 文件名自定义
mkdir vuepress-starter && cd vuepress-starter

2. 使用你喜欢的包管理器进行初始化

yarn init # npm init

3. 将 VuePress 安装为本地依赖

yarn add -D vuepress # npm install -D vuepress

4. 创建你的第一篇文档，VuePress 会以 docs 为文档根目录，所以这个 README.md 相当于主页：

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

5. 在 package.json 中添加一些 scripts

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

6. 在本地启动服务器

yarn docs:dev # npm run docs:dev

VuePress 会在 http://localhost:8080 (opens new window) 启动一个热重载的开发服务器。

2. 基础配置

在文档目录下创建一个 .vuepress 目录，所有 VuePress 相关的文件都会被放在这里。此时你的项目结构可能是这样：

.
├─ docs
│  ├─ README.md
│  └─ .vuepress
│     └─ config.js
└─ package.json

在 .vuepress 文件夹下添加 config.js，配置网站的标题和描述，方便 SEO：

module.exports = {
  title: 'TypeScript4 文档',
  description: 'TypeScript4 最新官方文档翻译'
}

此时界面类似于：

3. 添加导航栏

我们现在在页首的右上角添加导航栏，修改 config.js:

module.exports = {
    title: '...',
    description: '...',
    themeConfig: {
        nav: [
            { text: '首页', link: '/' },
            { 
                text: '冴羽的 JavaScript 博客', 
                items: [
                    { text: 'Github', link: 'https://github.com/mqyqingfeng' },
                    { text: '掘金', link: 'https://juejin.cn/user/712139234359182/posts' }
                ]
            }
        ]
    }
}

效果如下：

更多的配置参考 VuePress 导航栏。

4. 添加侧边栏

现在我们添加一些 md 文档，目前文档的目录如下：

.
├─ docs
│  ├─ README.md
│  └─ .vuepress
│     └─ config.js
|  └─ handbook
|     └─ ConditionalTypes.md
|       └─ Generics.md
└─ package.json

我们在 config.js 配置如下：

module.exports = {
    themeConfig: {
        nav: [...],
        sidebar: [
            {
                title: '欢迎学习',
                path: '/',
                collapsable: false, // 不折叠
                children: [
                    { title: "学前必读", path: "/" }
                ]
            },
            {
              title: "基础学习",
              path: '/handbook/ConditionalTypes',
              collapsable: false, // 不折叠
              children: [
                { title: "条件类型", path: "/handbook/ConditionalTypes" },
                { title: "泛型", path: "/handbook/Generics" }
              ],
            }
          ]
    }
}

对应的效果如下：

5. 更换主题

现在基本的目录和导航功能已经实现，但如果我还想要加载 loading、切换动画、模式切换（暗黑模式）、返回顶部、评论等功能呢，为了简化开发成本，我们可以直接使用主题，这里使用的主题是 vuepress-theme-reco：

现在我们安装 vuepress-theme-reco：

npm install vuepress-theme-reco --save-dev
# or
yarn add vuepress-theme-reco

然后在 config.js 里引用该主题：

module.exports = {
  // ...
  theme: 'reco'
  // ...
}  

刷新一下页面，我们会发现一些细节的改变，比如加载时的 loading 动画、以及支持切换暗黑模式：

6. 添加文章信息

但我们也会发现，像条件类型这一篇文章，条件类型（Conditional Types） 竟然出现了两遍，这是因为这个主题自动提取了第一个大标题作为本文的标题，我们可以在每篇文章的 md 文件中添加一些信息修改：

---
title: 条件类型
author: 冴羽
date: '2021-12-12'
---

此时文章的效果如下：

但如果你不想要标题、作者、时间这些信息呢，我们可以在样式里隐藏，这个稍后会讲到。

7. 设置语言

注意，上图的文章时间，我们写入的格式为 2021-12-12 ，但是显示的是 12/12/2021，这是因为 VuePress 默认的 lang 为 en-US，我们修改一下 config.js：

module.exports = {
  // ...
  locales: {
    '/': {
      lang: 'zh-CN'
    }
  },
  // ...
}  

可以发现时间换了一种展示方式：

8. 开启目录结构

在原本的主题里，我们发现每篇文章的目录结构出现在左侧：

而 vuepress-theme-reco 将原有的侧边栏的中的多级标题移出，生成子侧边栏，放在了页面的右侧，如果你要全局开启，可在页面 config.js 里设置开启：

module.exports = {
  //...
  themeConfig: {
    subSidebar: 'auto'
  }
  //...
}

此时效果如下：

9. 修改主题颜色

VuePress 基于 Vue，所以主题色用的是 Vue 的绿色，然而 TypeScript 的官方色则是蓝色，那如何修改 VuePress 的主题色呢？

你可以创建一个 .vuepress/styles/palette.styl 文件，文件代码如下：

$accentColor = #3178c6

此时可以发现主题颜色变了：

更多的颜色修改参考 VuePress 的 palette.styl。

10. 自定义修改样式

如果你想自定义修改一些 DOM 元素的样式呢？就比如在暗黑模式下：

我们发现用作强调的文字颜色比较暗淡，在暗黑模式下看不清楚，我想改下这个文字的颜色和背景色呢？

而 VuePress 提供了一种添加额外样式的简便方法。你可以创建一个 .vuepress/styles/index.styl 文件。这是一个 Stylus 文件，但你也可以使用正常的 CSS 语法。

我们在 .vupress 文件夹下创建这个目录，然后创建 index.styl 文件，代码如下：

// 通过检查，查看元素样式声明
.dark .content__default code {
    background-color: rgba(58,58,92,0.7);
    color: #fff;
}

此时文字就清晰了很多：

那之前我们提到的隐藏每篇文章的标题、作者、时间呢，其实也是类似的方式：

.page .page-title {
   display: none;
}

最后的效果如下：

11. 部署

我们的博客就算是正式的做好了，接下来我们部署到免费的 Github Pages 上。我们在 Github 上新建一个仓库，这里我取得仓库名为：learn-typescript。

对应，我们需要在 config.js 添加一个 base 路径配置：

module.exports = {
    // 路径名为 "/<REPO>/"
    base: '/learn-typescript/',
    //...
}

最终的 config.js 文件内容为：

module.exports = {
    title: 'TypeScript4 文档',
    description: 'TypeScript4 最新官方文档翻译',
    base: '/learn-typescript/',
    theme: 'reco',
    locales: {
        '/': {
          lang: 'zh-CN'
        }
    },
    themeConfig: {
        // lastUpdated: '上次更新',
        subSidebar: 'auto',
        nav: [
            { text: '首页', link: '/' },
            { 
                text: '冴羽的 JavaScript 博客', 
                items: [
                    { text: 'Github', link: 'https://github.com/mqyqingfeng' },
                    { text: '掘金', link: 'https://juejin.cn/user/712139234359182/posts' }
                ]
            }
        ],
        sidebar: [
            {
                title: '欢迎学习',
                path: '/',
                collapsable: false,
                children: [
                    { title: "学前必读", path: "/" }
                ]
            },
            {
              title: "基础学习",
              path: '/handbook/ConditionalTypes',
              collapsable: false,
              children: [
                { title: "条件类型", path: "/handbook/ConditionalTypes" },
                { title: "泛型", path: "/handbook/Generics" }
              ],
            }
          ]
    }
}

然后我们在项目 vuepress-starter 目录下建立一个脚本文件：deploy.sh，注意修改一下对应的用户名和仓库名：

#!/usr/bin/env sh

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

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

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

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

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

cd -

然后命令行切换到 vuepress-starter 目录下，执行 sh deploy.sh，就会开始构建，然后提交到远程仓库，注意这里提交到了 gh-pages 分支，我们查看下对应仓库分支的代码：

我们可以在仓库的 Settings -> Pages 中看到最后的地址：

像我最后生成的地址就是 https://mqyqingfeng.github.io/learn-typescript/

至此，我们完成了 VuePress 和 Github Pages 的部署。

系列文章

系列文章目录地址：https://github.com/mqyqingfeng/Blog

微信：「mqyqingfeng」，加我进冴羽唯一的读者群。

如果有错误或者不严谨的地方，请务必给予指正，十分感谢。如果喜欢或者 有所启发，欢迎 star，对作者也是一种鼓励。

[FangzhouSu]

如果我想频繁更新我这个线上的文档 并且让他人也可以参与进来文档共建 是不是把vuepress-start这个文件夹都提到github上来最好呢？ 👆刚才试了一下 貌似是不行 那就只有每次修改之后都打包 npm run docs:build 一下再提交了么orz 另外 感谢讶羽大大的分享！

[zxl7]

如果我想一起写下这个最好的我可以写下我呢？ 👆刚才试了一下，好像文档好像没有，那么只有那么一次打包npm运行：build一下再修改了么，或者是 感谢羽大的分享！

巧了，宝， 应该是克隆 master 分支到本地仓库，然后本地仓库打包出的gh-pages文件提PR 给原始仓库 gh-pages

[FangzhouSu]

如果我想一起写下这个最好的我可以写下我呢？ 👆刚才试了一下，好像文档好像没有，那么只有那么一次打包npm运行：build一下再修改了么，或者是 感谢羽大的分享！

巧了，宝， 应该是克隆 master 分支到本地仓库，然后本地仓库打包出的gh-pages文件提PR 给原始仓库 gh-pages

好巧！ 这两天实践了一下 就 每更新一次 打包一下 然后初始化仓库 提交commit 然后git push -f强制覆盖远程仓库对应分支 （我取名叫 init-pages) 然后在线版本就更新了 虽然有点麻烦 但是也没啥问题😂

[Zhengqbbb]

期待到时候使用 Vuepress-next | 我摸爬滚打了一整年，到时候基建任务交给我hhhh

[Zhengqbbb]

如果不想 -f 强行推送的话可以有另一套shell脚本方案。 脚本思路：

1. clone 两份 同一仓库 代码，一份分支假设是 main 另一份分支切到gh-pages
2. 在mian中运行脚本把dist文件 cp 到另一个的仓库
3. cd 到另一个仓库，push diff代码

毕竟 -f 强制覆盖的风险系数还是很高的，（这种经历就是瞬间不停冒冷汗，不要问我怎么知道的 :) ）

[gmh-ally]

sh deploy.sh sh 是要安装什么包吗

[Zhengqbbb]

sh deploy.sh sh 是要安装什么包吗

你可以这么理解

• 所谓的脚本就是带有逻辑的命令集合文件。可以很方便的避免重复性工作（类比上面的发布过程），而sh就是使用shell来启动脚本文件的，类比node中package.json中定义script，你可以简单一句话就可以运行起来
• 而shell是大多数终端中自带的，所以不需要安装包
• ps：脚本逻辑也是有规范的比如shell遵循POSIXShell规范，恰恰windows的CMD和powershell不遵循，所以.sh脚本文件在windows寸步难行（类比你的js脚本文件使用python是无法运行的），所以建议windows用户安装WSL搭配windows-terminal使用

[xuxuejin]

整个项目是一个 git 仓库，执行 sh 脚本，在生成的 dist 目录种还要再初始化一个仓库，push 会报错，没法部署。

[Zhengqbbb]

整个项目是一个 git 仓库，执行 sh 脚本，在生成的 dist 目录种还要再初始化一个仓库，push 会报错，没法部署。

发一下脚本，或者仓库我可以看看

[xuxuejin]

我看了一下你的仓库，master 分支没有什么，gh-pages 分支是打包后的产物。我是想实现，master 是 vuePress的写作仓库，gh-pages是打包产物的仓库，这样 master 文档有版本管理，产物也有版本管理

[Zhengqbbb]

@xuxuejin 你说的是在一个存储库存在两份版本管理吗，这样应该不行 你需要两个存储库，用脚本来管理就可以 详情可以看我负责仓库 希望能帮助到你： https://github.com/x-cmd/official-doc https://github.com/x-cmd/official-website

[xuxuejin]

@Zhengqbbb 好的，谢谢你，我知道了

[shyhhh]

羽哥 reco 的加载界面好像没了

[hytsister]

引入主题的时候 Uncaught Error: Cannot find module '@theme/mixins/posts' 报错

[xiaojuan-xu]

赞赞

[rongweihe]

2023 最新，GitHub 在后面把默认的 master 分支改成了 main 分支，所以这里面的 master 应该改为 main ，不然会报错

git push -f git@github.com:mqyqingfeng/learn-typescript.git master:gh-pages

[hequan-Bill]

你好，想问一下在部署运行之后，但是在Github上的Pages却没有看到相对应的出现，这是什么原因呢

[lichengcan]

本地跑没有问题，build打包后就这样了，请问下有人知道是什么问题吗

[lichengcan]

本地跑没有问题，build打包后就这样了，请问下有人知道是什么问题吗

部署后F12显示js找不到

[danghfz]

本地跑没有问题，build打包后就这样了，请问下有人知道是什么问题吗

这个是路径的问题，你仔细看base那个，或者查看打包的静态文件里面的js文件，css什么的路径都是错的

[wyz210052253]

sh deploy.sh sh 是要安装什么包吗

win系统可以在电脑中安装git,然后在你项目根文件夹里面运行git命令行，执行sh deploy.sh也可以。需要你本地的git和github设置了ssh。

[Arthur253896]

本地跑没有问题，build打包后就这样了，请问下有人知道是什么问题吗

部署后F12显示js找不到

请问解决了吗

[Arthur253896]

z这是为什么啊

[hph31]

z这是为什么啊

可能是有档案放错位置，我之前是因为config.js没放进.vuepress

[dcj00]

本地跑没有问题，build打包后就这样了，请问下有人知道是什么问题吗

加上base配置，图上写的不对：应该是 base: '/你的仓库的名字/' 还有就是部署后，要等个3-5分钟，等它更新才能看到效果。

[Peter-hcz]

部署这一块看不懂有懂的大佬吗？

[labuladong]

谢谢大佬分享。遇到一个中文路径引用图片时失败的问题，可以参见 这篇博客 解决。

[GreyFossssssss]

我也是同样问题

[miro-jian]

本地跑没有问题，build打包后就这样了，请问下有人知道是什么问题吗

需要设置base路径 /路径/ 不然css，js文件地址都不对

[kequeen]

总感觉这种实现方式还是有点ugly

[Z-p-github]

感谢大佬

[c2mx]

https://ts.yayujs.com/ 域名SSL证书过期了 :rotating_light:

[xtt-nora]

(undefined) assets/js/styles.d6073527.js from Terser Error: error:0308010C:digital envelope routines::unsupported at new Hash (node:internal/crypto/hash:68:19) at Object.createHash (node:crypto:138:10) at /Users/nora/update/vuepress-starter/node_modules/.pnpm/terser-webpack-plugin@1.4.5_webpack@4.47.0/node_modules/terser-webpack-plugin/dist/index.js:217:37 at Array.forEach () at TerserPlugin.optimizeFn (/Users/nora/update/vuepress-starter/node_modules/.pnpm/terser-webpack-plugin@1.4.5_webpack@4.47.0/node_modules/terser-webpack-plugin/dist/index.js:160:259)