📚 Hugo + PaperMod 完整使用手册

1. 完整目录结构详解

📂 你的博客文件夹结构（每个文件夹的作用）

your-blog/
├── 📁 archetypes/       # 文章模板（新建文章时自动套用）
│   └── default.md       # 默认文章模板
├── 📁 assets/           # 资源文件（CSS/JS，Hugo会自动处理）
├── 📁 content/          # ✅ 最重要！所有文章都在这里
├── 📁 data/             # 自定义数据文件（YAML/JSON）
├── 📁 layouts/          # 自定义模板（覆盖主题）
├── 📁 static/           # ✅ 静态资源（图片/文件，直接复制到网站）
│   ├── 📁 images/       # 放所有文章图片
│   └── favicon.ico      # 网站图标
├── 📁 themes/           # 主题文件夹（PaperMod在这里）
├── 📁 public/           # 构建后的网站（自动生成，不用管）
├── 📁 resources/        # Hugo缓存（自动生成）
├── ⚙️ hugo.toml         # ✅ 主配置文件
└── ⚙️ .gitignore        # Git忽略文件

2. Content 文件夹管理最佳实践

🎯 推荐的文章组织结构（按年/月/分类）

content/
├── 📁 posts/                    # ✅ 所有博客文章（必须叫这个名字）
│   ├── 📁 2026/                 # 按年份分文件夹
│   │   ├── 📁 06/               # 按月份分文件夹
│   │   │   ├── 第一篇文章.md    # 你的文章
│   │   │   └── 第二篇文章.md
│   │   └── 📁 07/
│   │       └── 第三篇文章.md
│   └── _index.md                # 文章列表页的说明（可选）
├── 📁 categories/               # 分类页面（自动生成）
├── 📁 tags/                     # 标签页面（自动生成）
├── about.md                     # 关于页面
├── archives.md                  # 归档页面
└── search.md                    # 搜索页面

✅ 简单版（新手推荐）

content/
├── 📁 posts/
│   ├── openclaw部署指南.md
│   ├── hugo搭建教程.md
│   └── ai工具对比.md
├── about.md
├── archives.md
└── search.md

3. 文章分类系统详解

🎯 Hugo 有 3 种分类方式，灵活组合使用

分类方式	用途	例子
Categories（分类）	大的分类，一篇文章一个	技术、随笔、教程
Tags（标签）	灵活标记，一篇文章多个	OpenClaw、Hugo、AI
Series（系列）	系列文章，连载用	OpenClaw 从入门到精通

📝 完整的文章 Front Matter 模板（复制即用）

每篇文章开头都要有这个：

---
# 🔴 基础信息（必填）
title: "OpenClaw 完整部署指南（Windows）"
date: 2026-06-14T23:00:00+08:00
draft: false                          # true=草稿，false=发布

# 🟠 分类系统
categories: ["技术教程"]               # 分类（数组，一般写一个）
tags: ["OpenClaw", "部署", "Windows"]  # 标签（可以写多个）
series: ["OpenClaw 从入门到精通"]       # 系列文章（可选）

# 🟡 SEO 优化
description: "Windows 系统下 OpenClaw 完整部署步骤，从环境搭建到运行测试"
keywords: ["OpenClaw", "部署", "Windows", "豆包"]

# 🟢 文章显示控制
showToc: true                          # 显示目录
TocOpen: true                          # 默认展开目录
hidemeta: false                        # 隐藏元信息（日期、作者等）
comments: false                        # 开启评论
disableHLJS: false                     # 禁用代码高亮
disableShare: false                    # 禁用分享按钮
hideSummary: false                     # 隐藏摘要
searchHidden: false                     # 搜索中隐藏
ShowReadingTime: true                   # 显示阅读时间
ShowBreadCrumbs: true                   # 显示面包屑
ShowPostNavLinks: true                  # 显示上下篇
ShowWordCount: true                     # 显示字数

# 🔵 封面图（可选）
cover:
    image: "/images/openclaw-cover.jpg"
    alt: "OpenClaw 部署"
    caption: "OpenClaw 完整部署教程"
    relative: false
    hidden: false
---

## 正文从这里开始

你的文章内容...

📌 分类、标签、系列的区别（例子）

---
title: "OpenClaw 安装教程"
categories: ["技术教程"]           # ✅ 大分类：这是一篇技术教程
tags: ["OpenClaw", "安装", "AI"]   # ✅ 标签：涉及这些技术点
series: ["OpenClaw 实战系列"]      # ✅ 系列：属于这个连载
---

注意：series（系列）不是 Hugo 默认启用的分类体系，需要在 hugo.toml 中添加 [taxonomies] 区块。
# 分类体系：启用分类、标签、系列
[taxonomies]
category = "categories"
tag = "tags"
series = "series"

效果：

点「技术教程」分类 → 看到所有教程类文章
点「OpenClaw」标签 → 看到所有 OpenClaw 相关文章
点「OpenClaw 实战系列」→ 看到整个连载的所有文章

4. Hugo 所有常用命令速查表

🚀 核心命令（每天都用）

命令	作用	例子
`hugo server -D`	本地预览（含草稿）	✅ 写文章必开
`hugo new posts/文章名.md`	新建文章	`hugo new posts/我的第一篇.md`
`hugo`	构建生产版本	生成 public 文件夹
`hugo version`	查看 Hugo 版本

📝 新建文章的各种方式

1. 普通文章（最常用）

hugo new posts/文章标题.md
# 生成：content/posts/文章标题.md

2. 按日期分类（推荐，整洁）

hugo new posts/2026/06/文章标题.md
# 生成：content/posts/2026/06/文章标题.md

3. 页面（关于、友链等）

hugo new about.md
# 生成：content/about.md

4. 文章包（带图片的文章，推荐！）

hugo new posts/我的文章/index.md
# 生成：content/posts/我的文章/index.md
# 图片就放在同一个文件夹里：
# content/posts/我的文章/图片1.jpg

🔧 其他有用命令

# 构建并显示详细信息
hugo -v

# 构建到指定目录
hugo -d ../output

# 忽略缓存重新构建
hugo --ignoreCache

# 检查坏链
hugo check links

# 查看环境信息
hugo env

5. 完整写文章工作流（带完整例子）

🎯 步骤 1：新建文章（终端执行）

# 进入博客目录
cd E:\9_Blog\meng-blog

# 新建文章
hugo new posts/OpenClaw完整部署指南.md

✅ 自动生成文件：content/posts/OpenClaw完整部署指南.md

🎯 步骤 2：编辑文章 Front Matter

打开文件，开头已经自动生成了，你补充完整：

---
title: "OpenClaw 完整部署指南（Windows 版）"
date: 2026-06-14T23:30:00+08:00
draft: true                          # 先设为草稿

categories: ["技术教程"]
tags: ["OpenClaw", "部署", "Windows", "豆包"]
series: ["OpenClaw 从入门到精通"]

description: "Windows 系统下 OpenClaw 从零开始部署的完整图文教程"
showToc: true
TocOpen: true
---

🎯 步骤 3：本地预览（边写边看）

hugo server -D

打开浏览器：http://localhost:1313

✅ 改完自动刷新，实时预览！

🎯 步骤 4：写正文（Markdown 例子）

## 一、准备工作

### 1.1 系统要求

- Windows 10/11 64位
- 至少 8GB 内存

### 1.2 下载安装包

# 下载 OpenClaw（提示：建议用 Git 下载，方便后续更新）
git clone https://github.com/xxx/OpenClaw.git

## 二、开始安装
…（继续写）

🎯 步骤 5：发布文章

写完了，确认没问题：

把 draft: true 改成 draft: false
关闭 hugo server（Ctrl+C）
提交推送：

git add .
git commit -m "新增：OpenClaw 完整部署指南"
git push

✅ 1 分钟后，网站自动更新！

🎯 步骤 6：插入图片（两种方式）

方式 A：全局图片（推荐，简单）

把图片放到 static/images/ 文件夹
文章里引用：

![OpenClaw 界面](/images/openclaw-screenshot.png)

方式 B：文章包（图片和文章在一起）

# 新建文章包
hugo new posts/openclaw-tutorial/index.md

# 图片放同一个文件夹
# content/posts/openclaw-tutorial/screenshot.png

# 文章里直接引用
![截图](screenshot.png)

6. PaperMod 高级功能配置

🔍 开启全文搜索

新建 content/search.md：

---
title: "全站搜索"
layout: "search"
draft: false
ShowToc: false
ShowBreadCrumbs: false
---

配置文件加菜单：

[[menu.main]]
  identifier = "search"
  name = "搜索"
  url = "/search/"
  weight = 50

📅 开启文章归档

新建 content/archives.md：

---
title: "文章归档"
layout: "archives"
url: "/archives/"
summary: archives
draft: false
ShowBreadCrumbs: false
---

配置文件加菜单：

[[menu.main]]
  identifier = "archives"
  name = "归档"
  url = "/archives/"
  weight = 40

💬 开启评论系统（Giscus，免费）

前置条件（3 项必须全部满足）

前置条件（3 项必须全部满足）
- 仓库必须为公开（Public）状态：私有仓库访客无法查看 Discussion，评论区会加载失败
- 仓库已开启 Discussions 功能：
	- 打开仓库 Settings 页面
	- 下拉找到「Features」板块，勾选「Discussions」
- 已安装 Giscus 官方应用：
	- 打开 https://github.com/apps/giscus
	- 点击「Install」，选择你的博客仓库并完成授权

打开：https://giscus.app/zh-CN，按步骤配置，得到你的配置

- 打开 Giscus 官方配置页：https://giscus.app/zh-CN
- 顶部语言选择「简体中文」
- 仓库配置
	- 在输入框填入你的仓库，格式为 用户名/仓库名
- 页面 ↔ Discussion 映射关系
	- 推荐选择「Discussion 的标题包含页面的 pathname」
	- 勾选「使用严格的标题匹配」，避免不同页面串评论
- Discussion 分类
	- 选择「Announcements（公告）」分类
	- 该分类只有仓库维护者和 Giscus 机器人能创建新帖，可有效防止垃圾内容
- 特性选项（推荐配置）
	✅ 启用主帖子上的反应
	✅ 将评论框放在评论上方（用户不用滚到底就能发评论）
	✅ 懒加载评论（评论区延迟加载，提升页面首屏速度）
- 主题选择
	- 选择「preferred_color_scheme」，自动跟随博客的深浅色模式切换
- 提取核心参数
	- 配置完成后，页面底部会生成一段 <script> 代码，从中提取 4 个关键值备用：
        data-repo：仓库名
        data-repo-id：仓库唯一 ID（一长串随机字符）
        data-category：分类名，通常为 Announcements
        data-category-id：分类唯一 ID（一长串随机字符）

在 hugo.toml 的 [params] 区块中添加以下完整配置，层级不能错：

[params]
  # 全局开启评论功能
  comments = true

  # Giscus 评论详细配置
  [params.giscus]
    repo = "your/your-blog"
    repoID = "从giscus页面复制的repoID"
    category = "Announcements"
    categoryID = "从giscus页面复制的categoryID"
    mapping = "pathname"
    strict = 1
    reactionsEnabled = 1
    emitMetadata = 0
    inputPosition = "top"
    theme = "preferred_color_scheme"
    lang = "zh-CN"
    loading = "lazy"

创建评论模板文件

你的博客根目录/
└── layouts/
    └── partials/
        └── comments.html   ← 新建这个文件

文件内容如下：

<!-- Giscus 评论系统 -->
<script src="https://giscus.app/client.js"
        data-repo="ZMDragon/mengblog-comments"
        data-repo-id="你的repoID，从giscus官网复制"
        data-category="Announcements"
        data-category-id="你的categoryID，从giscus官网复制"
        data-mapping="pathname"
        data-strict="1"
        data-reactions-enabled="1"
        data-emit-metadata="0"
        data-input-position="top"
        data-theme="preferred_color_scheme"
        data-lang="zh-CN"
        data-loading="lazy"
        crossorigin="anonymous"
        async>
</script>

说明：PaperMod 的文章详情页（single.html）会自动调用 layouts/partials/comments.html 这个模板，只要全局开启了 comments = true，就会在文章底部渲染这个文件里的内容

本地预览用生产环境模式。hugo server 默认是 development 开发环境，部分主题会在开发环境禁用评论、统计这类第三方脚本，避免调试干扰。

hugo server -D -e production
# -D：显示草稿文章
# -e production：强制以生产环境运行，评论、压缩、指纹全部生效
# 启动后打开单篇文章详情页，拉到最底部看评论区

每篇文章可以单独进行评论的开关。

---
title: "Windows部署博客"
date: 2026-06-14T00:00:00+08:00
draft: false
# comments: false  ← 如果有这行，删掉或改为true
---

工作原理
第一篇评论发布时，Giscus 会自动在仓库 Discussions 中创建对应页面的讨论帖
后续该页面的所有评论都会回复到同一个 Discussion 下
访客需使用 GitHub 账号登录后才能评论，天然抵御垃圾评论
你可以直接在 GitHub 仓库的 Discussions 板块中管理、回复、删除评论
常见踩坑提醒
仓库必须公开，私有仓库 100% 加载失败
repoID 和 categoryID 为必填项，填错会导致评论区空白
评论默认仅在文章详情页显示，首页、列表页不渲染
若不显示，先检查 comments = true 是否位于 [params] 层级下，嵌套错误会导致失效

📊 开启网站统计（Cloudflare Analytics）

直接在 Cloudflare 开启即可，零配置！

7. 常见问题与解决方案

❌ 问题 1：构建报错 `paginate deprecated`

解决：

# 旧的（删除）
paginate = 10

# 新的（加上）
[pagination]
  pagerSize = 10

❌ 问题 2：文章不显示

检查：

draft: false 了吗？
日期是不是在未来？
hugo server -D 能看到吗？（-D 显示草稿）

❌ 问题 3：图片不显示

检查：

图片是不是在 static/images/ 里？
路径是不是 /images/xxx.png（开头有 /）？

❌ 问题 4：Git 推送失败

解决：

# 先拉取再推送
git pull
git add .
git commit -m "更新"
git push

🎯 最后：日常工作流总结

每天写文章就这 5 步：

# 1. 拉取最新（防止冲突）
git pull

# 2. 新建文章
hugo new posts/文章名.md

# 3. 本地预览，边写边看
hugo server -D

# 4. 写完，draft 改 false
# 5. 三件套发布
git add .
git commit -m "新增：xxx"
git push

✅ 就这么简单！

📚 Hugo + PaperMod 完整使用手册#

目录#

1. 完整目录结构详解#

📂 你的博客文件夹结构（每个文件夹的作用）#

2. Content 文件夹管理最佳实践#

🎯 推荐的文章组织结构（按年/月/分类）#

✅ 简单版（新手推荐）#

3. 文章分类系统详解#

🎯 Hugo 有 3 种分类方式，灵活组合使用#

📝 完整的文章 Front Matter 模板（复制即用）#

📌 分类、标签、系列的区别（例子）#

4. Hugo 所有常用命令速查表#

🚀 核心命令（每天都用）#

📝 新建文章的各种方式#

1. 普通文章（最常用）#

2. 按日期分类（推荐，整洁）#

3. 页面（关于、友链等）#

4. 文章包（带图片的文章，推荐！）#

🔧 其他有用命令#

5. 完整写文章工作流（带完整例子）#

🎯 步骤 1：新建文章（终端执行）#

🎯 步骤 2：编辑文章 Front Matter#

🎯 步骤 3：本地预览（边写边看）#

🎯 步骤 4：写正文（Markdown 例子）#

🎯 步骤 5：发布文章#

🎯 步骤 6：插入图片（两种方式）#

方式 A：全局图片（推荐，简单）#

方式 B：文章包（图片和文章在一起）#

6. PaperMod 高级功能配置#

🔍 开启全文搜索#

📅 开启文章归档#

💬 开启评论系统（Giscus，免费）#

工作原理#

常见踩坑提醒#

📊 开启网站统计（Cloudflare Analytics）#

7. 常见问题与解决方案#

❌ 问题 1：构建报错 paginate deprecated#

❌ 问题 2：文章不显示#

❌ 问题 3：图片不显示#

❌ 问题 4：Git 推送失败#

🎯 最后：日常工作流总结#

每天写文章就这 5 步：#