使用hugo从0搭建blog并部署到github Pages

04 Jun, 2024

本教程旨在教会你使用hugo+github pages+github actions搭建一个完全免费的个人博客。其中关于一些基本概念比如git、hugo等不再过多介绍，关于hugo的具体设置也不在本教程范围内，如果你对这些概念不熟悉，建议先自行学习。重点会放在github pages和github actions的使用上。

安装

scoop install hugo # windows
brew install hugo # mac

hugo version # 验证是否正确安装

其他安装方法请参考hugo官网

初始化&安装bear主题

在这部分中，会实现初始化hugo项目并且给博客配置一个主题

hugo new site myblog # 会在本地目录创建一个名为myblog的文件夹，这个文件夹就是你的博客根目录
cd myblog
git init
git submodule add https://github.com/janraasch/hugo-bearblog.git themes/hugo-bearblog # 安装主题，这里使用submodule使博客主题作为自己项目的一个子模块方便后续维护

# 下面命令是后续同步主题修改
# git submodule update --remote

修改主题配置

将themes\hugo-bearblog\exampleSite下的content、static、hugo.toml复制到项目根目录
hugo.toml就是主题的配置文件，你可以根据自己的需求修改这个文件，具体可以查看官方文档

hugo new blog/test.md # 建立新的文章

hugo new bear.md # 建立新的页面

配置github pages + actions

一些前置知识（务必看）

当你在github上创建了一个仓库添加一个readme.md并且命名为 <用户名>.github.io 时，这个仓库就是你的github pages仓库，你可以通过 http://<用户名>.github.io 访问到该仓库下的readme.md。同理，当我们使用hugo生成的静态网页放到这个仓库下，我们就可以通过 http://<用户名>.github.io 访问到我们的博客。
那么我们现在的工作流就是hugo new生成文章-写文章-hugo命令生成静态文件-推送到github pages仓库；如果我们也想把博客的源代码通过git的方式管理起来（就是上面生成的myblog目录），那我们就需要再建立一个新的仓库用户存储源代码，并且每次增加文章后使用git add那一套推送。
github actions的作用是在我们推送代码到github仓库后，自动执行一些脚本，比如我们可以在推送代码后自动执行hugo命令生成静态文件并推送到github pages仓库，这样我们就不用手动执行hugo命令了。

配置步骤

创建key（注意这里的步骤可能随着github网站的更新有略微不同）

github-settings-Developer Settings-Personal access tokens-Tokens(classic)-generate new token
日期我一般选择不过期，Select scopes中选择repo全部、workflow、admin:repo_hook
填写任意名称，最好全部大写且有意义，复制，下面有用

建立<用户名>.github.io仓库

仓库名必须是<用户名>.github.io，建立好后这个仓库就是github pages
自定义域名：在该仓库的settings-pages-custom domain填入你的域名
还需要去你的域名服务商做域名解析，具体步骤可以自行搜索，这里不再阐述

建立博客源代码仓库

新建一个仓库，然后根据github的提示关联上面的myblog目录
在这个仓库中的settings-secrets and variables-actions-secrets-new repository secret-输入上面第一步创建key的名字和key
在myblog根目录建立.github/workflows/hugo.yaml，内容如下(注意下面的配置内容可能随着时间的改变而无效，如果无效就自行去搜索一个最新的配置文件)
下面hugo-version最好要填写和你本地hugo版本一样的版本号；external_repository和cname按照自己的填写即可，如果没有自定义域名省略cname即可

name: GitHub Pages

on:
  push:
    branches:
      - main # Set a branch to deploy

jobs:
  deploy:
    runs-on: ubuntu-20.04
    concurrency:
      group: ${{ github.workflow }}-${{ github.ref }}
    steps:
      - uses: actions/checkout@v3
        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.126.3"
          # 是否启用 hugo extend
          extended: false

      - name: Build
        run: hugo --minify

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          # github_token: ${{ secrets.GITHUB_TOKEN }} # 该项适用于发布到源码相同repo的情况，不能用于发布到其他repo
          personal_token: ${{ secrets.ACTION_ACCESS_TOKEN }}
          external_repository: <用户名>/<用户名>.github.io # 指定目标仓库
          publish_dir: ./public
          publish_branch: main # 指定目标分支
          cname: xxx.com # 如果你有自定义域名

测试

下面内容已经假设相关git和github的配置已经完成
运行下面命令后，如果没有什么意外，就是通过http://<用户名>.github.io或者你的自定义域名访问到你的博客了

cd myblog
hugo new blog/test.md # 建立新的文章
git add .
git commit -m "新增一篇文章"
git push

#Hugo #博客