hugo-blog/THEME_NOTES.md

Hugo PaperMod 主题结构分析

本文档用于记录当前博客所用 PaperMod 主题的结构、已启用能力和后续优化建议。

当前站点结构

hugo-blog/
├── hugo.toml                 # 站点主配置：标题、菜单、主页、参数、输出格式
├── content/
│   ├── about.md              # 关于页
│   ├── archives.md           # 归档页，使用 layout: archives
│   ├── search.md             # 搜索页，使用 layout: search
│   └── posts/                # 博客文章
├── themes/
│   └── PaperMod/             # PaperMod 主题，以 Git submodule 管理
└── public/                   # Hugo 构建产物，不建议作为源文件维护

PaperMod 的关键布局

PaperMod 的布局入口主要在 themes/PaperMod/layouts/：

文件	作用
baseof.html	全站 HTML 骨架，加载 head/header/main/footer
list.html	首页、列表页、section 页、taxonomy 页的主要模板
single.html	单篇文章页面模板
archives.html	归档页模板
search.html	搜索页模板
taxonomy.html	标签、分类等 taxonomy 页面模板
_partials/header.html	顶部导航栏
_partials/footer.html	页脚
_partials/home_info.html	Home-Info 模式主页介绍卡片
_partials/index_profile.html	Profile 模式主页
_partials/toc.html	文章目录
_partials/social_icons.html	社交图标

PaperMod 的三种主页模式

PaperMod 支持三种主页形态：

模式	配置方式	特点	当前是否使用
Regular	默认	直接展示文章列表，第一篇文章会突出显示	未使用
Home-Info	params.homeInfoParams	顶部显示一块个人介绍，下面仍然是文章列表	已使用
Profile	params.profileMode.enabled = true	更像个人名片页，适合作品集入口	未使用

当前选择 Home-Info，原因是它兼顾主页介绍和博客文章列表，适合个人技术博客。

已启用的功能

功能	配置/文件	说明
顶部菜单	hugo.toml [menu]	首页、文章、归档、标签、分类、搜索、关于
主页介绍	params.homeInfoParams	展示洛尘的博客定位和写作方向
归档页	content/archives.md + layout: archives	按时间浏览文章
搜索页	content/search.md + layout: search + outputs.home = JSON	Fuse.js 客户端全文搜索
标签/分类	taxonomies	自动生成 /tags/ 和 /categories/
文章目录	ShowToc = true	单篇文章自动生成目录
面包屑	ShowBreadCrumbs = true	方便确认当前位置
代码复制	ShowCodeCopyButtons = true	代码块可一键复制
阅读时间/字数	ShowReadingTime / ShowWordCount	文章元信息更完整
RSS	默认 + rss 图标	输出 /index.xml

当前配置建议

当前配置已经适合个人技术博客的基础形态：

1. 首页有个人介绍，不再只是文章列表。
2. 顶部导航有清晰的信息架构。
3. 搜索、归档、标签、分类都已具备。
4. 不修改主题源码，后续升级 PaperMod 更安全。

后续可优化方向

1. 增加站点图标和头像

可以添加：

assets/favicon.ico
assets/apple-touch-icon.png
assets/avatar.png

然后在 hugo.toml 的 [params.assets] 和 profileMode 中引用。

2. 是否切换到 Profile 首页

如果以后希望首页更像个人主页，可以启用：

[params.profileMode]
enabled = true
title = '洛尘'
subtitle = '自托管、运维、k3s 与自动化实践记录'

但缺点是首页文章列表会弱化。当前更推荐 Home-Info。

3. 增加文章系列 series

适合把文章组织成系列，例如：

• k3s 集群系列
• 自托管服务系列
• 终端环境系列
• Hermes Agent 系列

配置已预留：

[taxonomies]
series = 'series'

文章 frontmatter 里可加：

series:
  - k3s 集群实践

4. 增加自定义 CSS

如果要做更个性化的主页卡片、标签样式或代码块间距，可以通过 PaperMod 推荐的 override 方式添加：

assets/css/extended/custom.css

这样不需要改 themes/PaperMod 源码。

5. 增加友链或项目页

可以新增：

content/projects.md
content/friends.md

并加入顶部菜单。项目页可以放自建服务、脚本、运维实践合集。

6. 优化 SEO 与站点元信息

可继续补充：

• params.images：用于 Open Graph 分享封面
• copyright
• label.text
• 更具体的 description

不建议的做法

1. 不建议直接修改 themes/PaperMod/ 内部模板，除非必要。
2. 不建议把 public/ 当成源文件维护。
3. 不建议在公开文章中写真实公网 IP、密钥、Token 或精确基础设施位置。
4. 不建议一开始就做大量复杂定制，先保证内容结构稳定。