161 lines
5.0 KiB
Markdown
161 lines
5.0 KiB
Markdown
# Hugo PaperMod 主题结构分析
|
||
|
||
本文档用于记录当前博客所用 PaperMod 主题的结构、已启用能力和后续优化建议。
|
||
|
||
## 当前站点结构
|
||
|
||
```text
|
||
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. 增加站点图标和头像
|
||
|
||
可以添加：
|
||
|
||
```text
|
||
assets/favicon.ico
|
||
assets/apple-touch-icon.png
|
||
assets/avatar.png
|
||
```
|
||
|
||
然后在 `hugo.toml` 的 `[params.assets]` 和 `profileMode` 中引用。
|
||
|
||
### 2. 是否切换到 Profile 首页
|
||
|
||
如果以后希望首页更像个人主页，可以启用：
|
||
|
||
```toml
|
||
[params.profileMode]
|
||
enabled = true
|
||
title = '洛尘'
|
||
subtitle = '自托管、运维、k3s 与自动化实践记录'
|
||
```
|
||
|
||
但缺点是首页文章列表会弱化。当前更推荐 Home-Info。
|
||
|
||
### 3. 增加文章系列 series
|
||
|
||
适合把文章组织成系列，例如：
|
||
|
||
- k3s 集群系列
|
||
- 自托管服务系列
|
||
- 终端环境系列
|
||
- Hermes Agent 系列
|
||
|
||
配置已预留：
|
||
|
||
```toml
|
||
[taxonomies]
|
||
series = 'series'
|
||
```
|
||
|
||
文章 frontmatter 里可加：
|
||
|
||
```yaml
|
||
series:
|
||
- k3s 集群实践
|
||
```
|
||
|
||
### 4. 增加自定义 CSS
|
||
|
||
如果要做更个性化的主页卡片、标签样式或代码块间距，可以通过 PaperMod 推荐的 override 方式添加：
|
||
|
||
```text
|
||
assets/css/extended/custom.css
|
||
```
|
||
|
||
这样不需要改 `themes/PaperMod` 源码。
|
||
|
||
### 5. 增加友链或项目页
|
||
|
||
可以新增：
|
||
|
||
```text
|
||
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. 不建议一开始就做大量复杂定制，先保证内容结构稳定。
|