网站

使用 Hugo + Github 搭建个人博客

搭建思路

  1. Hugo 可以将 Markdown 文件转换为 HTML 文件；
  2. GitHub Pages 是 GitHub 提供的一个免费的静态网站托管服务，可用于托管个人网站、博客、文档、项目页面等静态内容；
  3. 创建 2 个 GitHub 仓库，一个是用于存放博客源文件的博客源仓库，另一个则是用于存放 Hugo 生成的 HTML 文件的 GitHub Pages 仓库；
  4. 使用 Github Actions 功能实现提交源码后自动发布。

准备工作

要想使用 Hugo + Github 搭建个人博客，首先要做好以下准备。

  1. 确保网络环境能够稳定地访问 Github；
  2. 创建 GitHub 账号；
  3. 安装 VS Code 与 Git；

以上内容只要稍加搜索，就能找到大量的教程，在此就不赘述了，接下来讲最后一项准备工作。

“我有东西可以写，我想写，我想一直写。”

如果你能做到前两点的话，请继续下一步；如果你能做到全部三点的话，也许哪天我就能看见你的博客；如果你连第一点都还做不到的话，不妨先试着写点什么。

安装 Hugo

Hugo 的安装方法很多，详情可以参考官方的 在 Windows 上安装 Hugo，建议安装扩展版（extended）。

创建 GitHub 仓库

创建博客源仓库

  1. 给仓库取一个你喜欢的名字（比如我用的是 BlogSource）；
  2. 选择 Private，设置为私有仓库；
  3. 勾选添加 README 文件；
  4. 创建仓库。
博客源仓库

创建 GitHub Pages 仓库

  1. 按照 <username.github.io> 的格式命名仓库，<username> 是自己的 GitHub 的用户名；
  2. 选择 Public，设置为公开仓库；
  3. 勾选添加 README 文件；
  4. 创建仓库。
GitHub Pages 仓库

克隆博客源仓库到本地

  1. 创建项目文件夹（比如我用的是 Blog）；

  2. 使用 cd 命令进入该文件夹（从此处开始建议使用 VS Code）；

1

cd Blog
  1. 克隆博客源仓库到项目文件夹，克隆时使用的 HTTPS 仓库链接在这里查看；
1

git clone https://github.com/Pomfret27/BlogSource.git

此处直接将 GitHub 上的远程仓库克隆到了本地，所以没必要再对仓库进行初始化，也不需要设置远程地址。

使用 Hugo 创建网站

  1. 使用 hugo new site [path] [flags] 命令可以在提供的目录中创建新的站点；

  2. 这里我选择在 Blog 文件夹下创建 BlogSource 站点，由于克隆下来的 BlogSource 文件夹非空，需要在命令后加上 -f来强制初始化；

1

hugo new site BlogSource -f
  1. 新的站点会有正确的结构，但尚无内容或主题，为了方便后续的操作，可以先选择一个有演示站点的主题。

配置主题

  1. 先到 官方的主题市场 选择一个喜欢的主题，下面我以自己使用的 Stack 为例；
  2. 一般主题的说明文档都会有安装相关的指导，各种主题存在差异，Stack 主题的安装可以参考 这个；
  3. 如果主题有演示站点 exampleSite 文件夹，可以讲其中的 content 文件夹和 toml 或是 yaml 文件复制到站点目录，并删除原先的 hugo.toml 文件；
  4. 将复制过来的配置文件中的 baseURL 改为自己的网址 https://<username>.github.io/，其他的修改可以等到网站搭建完成后再说。

使用 Hugo 新建文章

先使用 cd 命令进入站点目录，再使用 hugo new xxx.md 命令创建文章。这里先新建一篇空白文章，保证下一步本地预览的时候有文章就行。

1
2

cd BlogSource
hugo new post xxx.md

本地调试和预览

  1. 使用 hugo server 命令构建网站，如果想要清理未使用的缓存文件，可以在命令后面加上 --gc；
  2. 执行命令后，使用 Ctrl + 单击 打开终端中显示的链接 http://localhost:1313/，端口后默认为1313，可能会发生变化；
  3. 由于 Hugo 的构建速度很快，几乎可以即时地保存和查看更改。

GitHub 自动部署

生成 token

  1. 打开 GitHub，点击右上角的头像，再点击 Settings；
  2. 下拉页面，点击左侧的 Developer Settings；
  3. 点击左侧的 Personal access tokens，再点击 Tokens (classic);
  4. 点击右侧的 Generate new token，然后选择下面那个 Generate new token (classic)；
Generate new token
  1. 选择 token 到期时间，勾选 token 的访问范围，然后点击 Generate token 生成 token；
生成 token
  1. 生成的 token 只显示一次，所以一定要复制保存下来；

添加 secret

  1. 复制 token 后打开博客源仓库，点击 Settings，点击左侧的 Secrets and variables，点击 Actions；
Actions secrets
  1. 填写 Secret 名称，并将前面复制的 token 粘贴到 Secret 框中，添加 secret。
添加 secret

配置 GitHub Actions

这里先附上官方的 GitHub Actions for Hugo，感兴趣的可以自己看一下。

  1. 创建 workflow，在仓库根目录创建 .github 文件夹，再在里面创建 workflows 文件夹，之后创建一个 gh-pages.yml 文件，这个文件的名字也可以自取；
  2. 将下面的内容复制进 yml 文件；
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

name: GitHub Pages  #名字自取

on:
  push:
    branches:
      - main  # 这里的意思是当 main分支发生push的时候，运行下面的jobs，这里先改为github-actions
  pull_request:

jobs:
  deploy: # 任务名自取
    runs-on: ubuntu-latest  # 在什么环境运行任务
    concurrency:
      group: ${{ github.workflow }}-${{ github.ref }}
    steps:
      - uses: actions/checkout@v4 # 引用actions/checkout这个action，与所在的github仓库同名
        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@v3 # hugo官方提供的action，用于在任务环境中获取hugo
        with:
          hugo-version: 'latest'  # 获取最新版本的hugo
          extended: true  # 是否使用extended版本的hugo

      - name: Build
        run: hugo --minify # 使用hugo构建静态网页

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3 # 一个自动发布github pages的action
        if: github.ref == 'refs/heads/main'
        with:
          # github_token: ${{ secrets.GITHUB_TOKEN }} 该项适用于发布到源码相同repo的情况，不能用于发布到其他repo
          external_repository: <username>/<username>.github.io	# 发布到哪个repo
          personal_token: ${{ secrets.YOUR_SECRET_NAME }}	# 发布到其他repo需要提供上面生成的personal access token
          publish_dir: ./public	# 注意这里指的是要发布哪个文件夹的内容，而不是指发布到目的仓库的什么位置，因为hugo默认生成静态网页到public文件夹，所以这里发布public文件夹里的内容
          publish_branch: main	# 发布到哪个branch
  1. 修改 external_repository 为自己的 GitHub Pages 仓库，把 personal_token 的 YOUR_SECRET_NAME 改成前面设置的 secret 名称，如果使用了扩展版的 Hugo，还可以将 extended 改成 true。

发布内容

在本地写完文章，并用 hugo server 命令在 public 文件夹下生成静态网页后，只需要将本地仓库的内容推送到远程的博客源仓库，过一段时间，GitHub Actions 就会将博客源仓库的 public 文件夹的内容推送到 GitHub Pages 仓库，这样就可以通过 https://pomfret27.github.io 来访问博客网站了。

推送本地仓库可以使用下面的 git 命令：

1
2
3

git add .
git commit -m "提交信息"
git push origin main

上面三条命令先后完成了暂存、提交、推送三个操作，其中提交信息是必须填写的。

如果不想每次都手打命令，还可以使用 VS Code 的源代码管理功能。

源代码管理

步骤也是一样，先点击更改的加号来暂存所有更改，再输入提交信息，并点击提交按钮，提交完成后提交两字会变为同步，点击同步按钮即可完成推送。

如果你想要提交信息变得规范一些，可以安装 git-commit-plugin 插件来寻求帮助。

参考文献

碎碎念

文章中的部分内容并没有详细阐述，这部分内容将拆分到其他文章中，可以点击文章顶部的分类和底部的标签来查看相关文章哦。