Hugo + Github Pages 搭建个人博客

Hugo 是用 Go 实现的静态网站生成器，采用 Markdown 编写文章，自动生成静态站点文件，支持丰富的主题配置和 JavaScript 插件。同类工具还有 Gatsby、Jekyll、Hexo、Ghost 等。

1. 安装 Hugo

macOS 使用 Homebrew：

brew install hugo
hugo version   # 验证安装

2. 创建站点

hugo new site robin-site

生成的目录结构：

robin-site/
├── archetypes/    # 文章模板
├── assets/        # Hugo Pipes 处理的资源
├── content/       # Markdown 文章
├── data/          # 结构化数据
├── layouts/       # 布局文件
├── static/        # 静态文件 (CSS/JS/图片)
├── themes/        # 主题
└── config.toml    # 站点配置

3. 配置主题

在 Hugo Themes 挑选主题。推荐使用 git submodule 方式安装，便于版本管理：

cd robin-site/
git init
git submodule add https://github.com/xiaoheiAh/hugo-theme-pure themes/pure

在 config.toml 中启用：

theme = "pure"

更新主题：

git submodule update --init --recursive   # 初始化子模块
git submodule update --remote             # 同步最新版本

4. 撰写文章

hugo new posts/my-first-post.md

生成的文件默认 draft: true，改为 false 才会发布。推荐直接修改 archetypes/default.md，把 draft 默认值设为 false。

5. 本地预览

hugo server -D

浏览器打开 http://localhost:1313/ 即可实时预览。

6. 部署到 GitHub Pages

GitHub Pages 从仓库的 main 分支（根目录或 /docs 目录）提供静态文件服务。有两种使用场景：

6.1 个人主页（User Page）

仓库名必须为 [username].github.io，例如 jianzhnie.github.io。

# 1. 修改 config.toml
baseURL = "https://jianzhnie.github.io/"

# 2. 构建
hugo

# 3. 推送 public/ 到远程
cd public
git init
git remote add origin https://github.com/jianzhnie/jianzhnie.github.io.git
git add .
git commit -m "deploy"
git push -u origin main

以后更新：

hugo                        # 站点根目录构建
cd public && git add -A && git commit -m "update" && git push

6.2 项目页面（Project Page）

用 gh-pages 分支为任意仓库部署独立页面，适合项目文档或学习笔记。

以 deeplearning-notes 仓库为例：

hugo new site dl-notes
hugo new posts/transformer.md

# config.toml
baseURL = "https://jianzhnie.github.io/deeplearning-notes/"

hugo

cd public
git init
git checkout -b gh-pages
git remote add origin https://github.com/jianzhnie/deeplearning-notes.git
git add .
git commit -m "deploy"
git push -u origin gh-pages

访问 https://jianzhnie.github.io/deeplearning-notes/ 即可。

7. GitHub Action 自动部署

手动推送存在两个问题：步骤繁琐、源文件无法版本管理。用 GitHub Action 可以解决。

创建 .github/workflows/deploy.yml：

name: deploy

on:
  push:
  workflow_dispatch:
  schedule:
    - cron: "0 0 * * *"

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v3
        with:
          submodules: true
          fetch-depth: 0

      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: "latest"

      - name: Build
        run: hugo

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          personal_token: ${{ "{{ secrets.PERSONAL_TOKEN }}" }}
          external_repository: jianzhnie/jianzhnie.github.io
          publish_branch: main
          publish_dir: ./public
          commit_message: ${{ "{{ github.event.head_commit.message }}" }}

触发条件说明：

• push — 推送源码时自动构建部署
• workflow_dispatch — 支持手动触发
• schedule — 定时执行（不需要可删除）

Checkout 中 submodules: true 确保主题子模块被同步。部署到外部仓库需要先在 GitHub Settings > Developer settings > Personal access tokens 创建 Token，写入仓库的 Secrets。

8. 热门 Hugo 主题

搜索更多主题：在 GitHub 搜索 hugo theme。

9. 总结

日常发布流程：

# 新建文章
hugo new post/文章名.md

# 本地预览后构建
hugo

# 推送上线
cd public && git add -A && git commit -m "update" && git push

搭建一次，后续只需写 Markdown 文章、运行 hugo、push 三步即可发布。