博客搭建

起因 上一篇文章里说过我想开个博客记录学习——这篇讲博客本身是怎么搭起来的，以及搭建过程中真实踩过的几个坑。 技术栈选得很朴素：Hugo（静态站点生成器）+ PaperMod（主题）+ GitHub Pages（托管）+ Giscus（评论，底层是 GitHub Discussions）。 理论上这套 30 分钟能搞定的事，实际花了整整一个下午加一个晚上——其中大半时间耗在一个看似配置都对、但 Giscus 死活报 Unable to create discussion 的问题上。 下面按踩坑顺序记录。 1. 一波加 16 个 feature，让 agent 并行做 第一篇文章发出去之后，我列了一堆功能需求： 系列文章（taxonomy + 首页云 + 前后篇导航） 搜索框点击 bug 首页 taxonomy 云（分类 + 标签） 自定义 shortcode（alert / card / video） 代码语法高亮（chroma CSS） 代码块复制按钮 Giscus 评论 Mermaid 流程图 + KaTeX 数学公式 分享按钮（微博 + 复制链接） 多语言支持（加英文） 彩虹标签 图标科技感 …… 一共 16 项。我派了 11 个 agent 同时干，每只 agent 拿到独立的文件范围，互不重叠，跑完自己 commit + push。 ...

为什么开这个博客 学了一年多零零碎碎的东西，发现自己最容易巩固知识的方式是写下来——把别人文章里看过的、自己踩过的、调了半天才通的，全记一遍，比再读十遍笔记都记得牢。 所以这个博客的核心目的只有一个： 把学习中"有用的部分"沉淀下来，将来自己回来翻也翻得到。 这里会写什么 我会按下面几个方向持续更新： 方向 内容 编程语言 Python / Go / JavaScript 等的核心点回顾 Web / 前端 HTML / CSS / 框架要点，组件写法 系统与运维 Linux、容器、网络、性能排查 工具流 编辑器、命令行、调试、效率软件 PVE 服务器管理 安装、配置、使用 PVE 服务器 一段示例代码 技术博客少不了代码块，这是一段示例： 1 2 3 4 5 6 7 8 9 def fib(n: int) -> int: a, b = 0, 1 for _ in range(n): a, b = b, a + b return a # 算到第 10 项 for i in range(10): print(i, fib(i)) 行号自动显示，主题自带复制按钮。 相关阅读 Hugo + PaperMod 博客搭建：从 0 到评论上线，我踩过的坑 — 下一篇，讲我搭这个博客本身踩的坑（giscus repoId 格式、调试 agent 冲突等）。

本文是 Hugo + PaperMod 博客搭建：从 0 到评论上线，我踩过的坑 的「完整版」——上篇是叙事版，这篇是参考手册版。读这一篇就能掌握搭建这个博客用到的全部 Hugo 知识。 1. 什么是 Hugo Hugo 是一个用 Go 写的静态站点生成器（Static Site Generator, SSG）。你写 Markdown，Hugo 编译成 HTML，浏览器直接读 HTML 文件。 跟同类对比： 工具 语言 特点 Hugo Go 快——几千页也毫秒级编译 Jekyll Ruby 老牌，GitHub Pages 原生支持 Hexo Node.js 中文社区多 Gatsby React + GraphQL 适合复杂前端 Astro 多框架 现代，新兴 Hugo 的最大卖点是速度——几千篇文章的站，一次完整 build 通常 < 1 秒。本地 hugo server 改一行就热更新，几乎无感。 ℹ️Info > Hugo 是「无依赖」工具——单文件可执行（~30 MB），不装 Node、不装 Ruby、不装数据库。丢任何机器上都能跑。 > 2. 安装 macOS 1 brew install hugo Linux 1 2 3 4 5 # Debian/Ubuntu sudo apt install hugo # 或最新版（推荐） snap install hugo --channel=extended ⚠️Warning > 装 **`extended`** 版本——后面要用 Hugo Pipes 处理 SCSS，普通版不支持。 > Windows 1 2 choco install hugo-extended # 或 scoop install hugo-extended 验证 1 2 hugo version # hugo v0.158.0+extended ... 3. 初始化一个新站 1 2 hugo new site my-blog cd my-blog 生成结构： ...