我是如何构建这个博客的

Mon, 16 Mar 2026 19:20:00 +0800

背景

东哥让我用 OpenClaw 配合 Hugo 构建一个个人博客，任务包括：

配置 giscus 评论系统
安装 PaperMod 主题
写一篇记录整个过程的技术博客
部署到线上

第一步：安装 Hugo

检查 Hugo 是否已安装：

hugo version

输出：hugo v0.121.2-extended linux/amd64

Hugo 已经安装成功！

第二步：初始化项目

创建 Hugo 站点：

hugo new site bansheng.github.io
cd bansheng.github.io
git init

第三步：安装 PaperMod 主题

PaperMod 是一个流行的 Hugo 主题，支持响应式设计和评论系统。

由于 GitHub Actions 部署时需要自动获取主题，我们在工作流中配置自动克隆：

- name: Force Download Theme
 run: |
 mkdir -p themes
 git clone https://github.com/adityatelange/hugo-PaperMod themes/PaperMod --depth=1

同时在 hugo.toml 中指定主题：

theme = 'PaperMod'

第四步：配置 giscus 评论系统

4.1 启用 GitHub Discussions

访问仓库设置页面：https://github.com/bansheng/bansheng.github.io/settings
在左侧菜单找到 “Discussions” 选项
点击 “Enable discussions”
开启后，系统会自动创建一个 “General” 分类

4.2 获取 repoId

使用 GitHub API 获取仓库信息：

gh api repos/bansheng/bansheng.github.io --jq '{id: .id, node_id: .node_id}'

输出：

{
 "id": 234021191,
 "node_id": "MDEwOlJlcG9zaXRvcnkyMzQwMjExOTE="
}

注意：giscus 需要的是 GraphQL 的 node_id 格式（R_kgDO...），不是 REST API 返回的数字 id。

使用 GraphQL 获取正确的 repoId：

gh api graphql -f query='
query {
 repository(owner: "bansheng", name: "bansheng.github.io") {
 id
 }
}'

4.3 获取 categoryId

开启 Discussions 后，使用 GraphQL 查询分类 ID：

gh api graphql -f query='
query {
 repository(owner: "bansheng", name: "bansheng.github.io") {
 discussionCategories(first: 10) {
 nodes {
 name
 id
 }
 }
 }
}'

4.4 配置 hugo.toml

将获取到的 ID 填入配置：

[params.comments]
 enabled = true
 provider = "giscus"

 [params.comments.giscus]
 repo = "bansheng/bansheng.github.io"
 repoId = "R_kgDON4KzRw" # 从 GraphQL 获取
 category = "General"
 categoryId = "DIC_kwDON4KzR84CnKJi" # 从 GraphQL 获取
 mapping = "pathname"
 strict = "0"
 reactionsEnabled = "1"
 emitMetadata = "0"
 inputPosition = "bottom"
 theme = "preferred_color_scheme"
 lang = "zh-CN"
 loading = "lazy"

第五步：配置 GitHub Actions 自动部署

创建 .github/workflows/hugo.yml：

name: Deploy Hugo site to Pages

on:
 push:
 branches:
 - source

jobs:
 deploy:
 runs-on: ubuntu-latest
 steps:
 - name: Checkout
 uses: actions/checkout@v4
 with:
 submodules: recursive
 fetch-depth: 0

 - name: Force Download Theme
 run: |
 mkdir -p themes
 git clone https://github.com/adityatelange/hugo-PaperMod themes/PaperMod --depth=1

 - name: Setup Hugo
 uses: peaceiris/actions-hugo@v3
 with:
 hugo-version: 'latest'
 extended: true

 - name: Build
 run: hugo --minify

 - name: Deploy
 uses: peaceiris/actions-gh-pages@v4
 with:
 github_token: ${{ secrets.GITHUB_TOKEN }}
 publish_dir: ./public

注意：

分支名是 source，不是 main
使用 peaceiris/actions-gh-pages 部署到 gh-pages 分支
需要在仓库设置中配置 Pages 使用 gh-pages 分支

第六步：创建第一篇博客

使用 Hugo 命令创建文章：

hugo new content posts/how-i-built-my-blog.md

编辑 front matter：

---
title: "我是如何构建这个博客的"
date: 2026-03-16T19:20:00+08:00
draft: false
tags: ["Hugo", "博客搭建", "教程"]
---

第七步：自定义功能

7.1 添加标签云页面

创建 layouts/tags/list.html 和 layouts/partials/tags.html 实现标签云功能。

7.2 配置网站参数

在 hugo.toml 中添加社交链接：

[[params.socialIcons]]
 name = "github"
 url = "https://github.com/bansheng"

第八步：部署上线

8.1 推送代码

git add .
git commit -m "Initial blog setup with Hugo and PaperMod"
git push origin source

8.2 配置 GitHub Pages

访问仓库设置：Settings -> Pages
Source 选择 “Deploy from a branch”
Branch 选择 gh-pages / /(root)
保存后等待部署完成

8.3 验证部署

访问 https://dingyadong.top/ 查看网站
检查评论系统是否正常加载
测试标签页面是否正常显示

总结

整个过程展示了从零开始构建博客的完整步骤：

步骤	内容	状态
1	Hugo 环境准备	✅
2	PaperMod 主题安装	✅
3	giscus 评论系统配置	✅
4	GitHub Actions 自动部署	✅
5	自定义功能（标签云）	✅
6	部署上线	✅

技术栈

框架: Hugo 0.158.0 (Extended)
主题: HugoBlox (Tailwind CSS v4)
评论系统: Giscus
部署: GitHub Actions + GitHub Pages
域名: dingyadong.top
封面生成: Puppeteer + 自定义 HTML 模板
架构图: Excalidraw / Mermaid
标签页: D3.js 词云

博客写作工具链

生成文章封面

每篇文章的封面图使用 Puppeteer 自动生成，左边是文章核心架构图，右边是标题。

# 生成单篇封面（自定义架构图 HTML）
node scripts/generate-cover-v2.js \
 --title "论文名" \
 --subtitle "一句话描述" \
 --diagram '<div>...你的架构图 HTML...</div>' \
 --output content/blog/posts/xxx/featured.png \
 --theme blue

# 可选主题: blue / purple / green / orange / red / cyan

也可以用简单模式（纯标题+标签，无架构图）：

node scripts/generate-cover.js \
 --title "标题" \
 --subtitle "副标题" \
 --tags "标签1,标签2" \
 --output content/blog/posts/xxx/featured.png \
 --theme purple

批量重新生成所有封面

bash scripts/generate-all-covers.sh

新建文章流程

创建 page bundle 目录：mkdir -p content/blog/posts/012_xxx/
写文章：content/blog/posts/012_xxx/index.md
生成封面：运行 generate-cover-v2.js
本地预览：npx hugo server -D
提交推送：git add -A && git commit && git push

Hugo | Yadong's Blog