如何利用GithubAction发布Hugo博客

2022-04-05

Table of Contents

作为一个老网民，我还是很喜欢折腾博客的。从07年开始就玩各种博客，比如07年搜狐博客，那时候博客热很火，不亚于微博兴起的时候，于是我每天去刷我的搜狐博客访问量，是不是还专门去网吧写文章。后来还开了新浪博客，一直在新浪博客混混文字，大概一直在新浪博客写了4年。

再后来又买了独立主机，自己开WordPress写博客，无奈后来被人把主机给黑了。但是那时候很快啦，天天找WordPress好看的主题，去别的的WP 搜索好用的插件。各种互加友链。

当然后来还玩了很多其他的博客，比如Google的BlogSpot，Tumbler，对就是那个Tumbler。还有网易的LOFTER，新浪的绿洲。腾讯的QQ空间，微信公众号。

工作以后，有了Github page，看着大家都用Travis去自动化部署，于是也用HEXO搭建了一个。不过18年后一直没维护了，中途有次冲动想维护起来，发现怎么都跑不起来，于是就懒得动了。

最近大家都用Github Action自动化部署Blog。于是又折腾起来了。整个过程花了几个小时，担心以后忘记又记不起来，在这里简单做个记录。整个流程如下

1、本地安装Hugo
2、用Hugo写好Markdown文章 (hugo new posts/new_post.md) 3、然后将Markdown生成为静态文件
4、将生成的静态站点内容推送到Github发布

一、安装Hugo

mac： brew install hugo

其他系统安装方式见：https://gohugo.io/getting-started/installing/

二、生成静态站点

1、初始化站点

Hugo命令可以自动生成站点需要的文件，后续我们所有的操作命令将会在Hugo生成的目录下执行。

hugo new site hugo-blog

2、进入到hugo-blog目录，cd hugo-blog

3、安装主题
我是通过 git submodule 安装的，确保自己在hugo-blog目录下，执行命令：

git init
git submodule add https://github.com/xianmin/hugo-theme-jane.git themes/jane

4、启用主题

第三步完成后，需要在配置文件中启用主题，配置文件在hugo-blog根目录下。

echo 'theme = "jane"' >> config.toml

5、创建第一篇你的博文

hugo new posts/my-first-post.md

在下方接着写入文章内容即可。注意此时该文件为草稿状态，写作完成后需要改成 draft: false 才能部署。

6、启动 Hugo 预览服务器

Hugo 可以启动一个 Web 服务器，同时构建站点内容到内存中并在检测到文件更改后重新渲染，方便我们在开发环境实时预览对站点所做的更改。命令如下：

hugo server -D

添加 -D 选项以输出草稿状态的文章，执行成功后可以通过 http://localhost:1313/ 访问站点。

7、生成静态站点文件

当主题和文章等配置ok了，就可以生成静态站点界面。

hugo -D

添加 -D 选项可以在结果中包括草稿内容，默认情况下静态页面会输出到根目录下的 public 文件夹中。

三、利用Github Action发布

1、创建静态站点项目

在Github创建一个公共项目，名为username.github.io，这个仓库只放静态内容。注意，username一定要和github用户名相同。

2、创建hugo-blog项目

然后再Github新创建一个私有项目，名字为hugo-blog（保持与上面第二步《生成静态站点》的目录名字相同），然后添加为我们本地项目文件夹的远程仓库（第二步创建的利用Hugo自动生成的目录）。这个仓库用来维护站点配置和原始的文章内容。

3、添加子模块

因为public里面存的是静态站点文件，所以我们在public创建一个git的子模块，之后这个目录将以 git@github.com:JerryGoodLuck/JerryGoodLuck.github.io.git 作为远程仓库。

git submodule add -b main git@github.com:JerryGoodLuck/JerryGoodLuck.github.io.git public

4、baseurl配置

确保配置文件中的 baseUrl 已经设置为了 <USERNAME>.github.io

5、其他配置

一般还有其他的很多配置，可以根据自己的偏好来配置

6、添加workflows

这个文件所定义的workflow 基于项目仓库运行，但我们需要将运行过程生成的静态文件推送到个人主页仓库 JerryGoodLuck.github.io 完成发布. 相关的deploy任务中按照文档的 Deploy to external repository external_repository 一节做了专门的配置。

我的配置文件如下


name: github pages
   
on:
  push:
    branches:
      - main
  
jobs:
  deploy:
    runs-on: ubuntu-18.04
    steps:
      - uses: actions/checkout@v2
        with:
          submodules: true  # Fetch Hugo themes (true OR recursive)
          fetch-depth: 0    # Fetch all history for .GitInfo and .Lastmod
   
      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: '0.79.1'
          extended: true
   
      - name: Build
        run: hugo --minify

   
      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          deploy_key: ${{ secrets.ACTIONS_DEPLOY_KEY }}
          external_repository: JerryGoodLuck/JerryGoodLuck.github.io
          publish_branch: main
          publish_dir: ./public

7、在本地电脑生成SSH密钥

ssh-keygen -t rsa -b 4096 -C "$(git config user.email)" -f gh-pages -N ""
 # 将在当前目录生成如下密钥文件:
 #   gh-pages.pub (公钥)
 #   gh-pages     (私钥)

8、配置密钥

在 GitHub 分别进入项目仓库和个人主页仓库的 Settings 页面：

将公钥 gh-page.pub添加到 JerryGoodLuck.github.io项目的setting下的Deploy Keys，命名为HEXO_DEPLOY_PUB， 并设置为 Allow write access。
将私钥 gh-pages 添加到hugo-blog的secrets下的Actions，命名为ACTIONS_DEPLOY_KEY

9、测试

接下来我们测试一下。在本地新增一个测试文章，git提交并推送到Github，预览效果后提交并推送，然后在项目仓库的 GitHub Actions 页面检查相应的 workflow 是否运行成功。

不出意外的话，很快个人主页仓库将新增一个由该 workflow 创建的提交，访问个人博客页面也会发现页面已经更新。

四、总结：

这次利用Github Action搭建Hugo的过程中，还是遇到不少坑。

1、不知道Github Action的语法以及配置文件怎么写，参考文档

2、运行workflow总是失败，后来发现几个关键点：

一个就是静态站点要以submodule的模式放在public目录下

 二个是主题也要是submodule的模式

3、公私钥Key配置的不正确。

### update 2022-08-07 17:06:39 Sunday

Jane主题 full-config : https://github.com/xianmin/hugo-theme-jane/blob/master/exampleSite/full-config.toml