configure homepage and site navigation

2026-05-28 22:50:42 +08:00
parent ce2986fa93
commit e0d7f07c24
5 changed files with 331 additions and 1 deletions
--- a/THEME_NOTES.md
+++ b/THEME_NOTES.md
@@ -0,0 +1,160 @@
+# 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. 不建议一开始就做大量复杂定制，先保证内容结构稳定。
--- a/content/about.md
+++ b/content/about.md
@@ -0,0 +1,43 @@
+---
+title: '关于'
+draft: false
+hiddenInRss: true
+disableShare: true
+ShowBreadCrumbs: true
+ShowToc: true
+---
+
+你好，我是洛尘。
+
+这里是我的个人技术博客，主要记录自托管服务、Linux 运维、k3s 集群、Tailscale 组网、Hugo 博客、终端环境和自动化实践。
+
+## 我关注什么
+
+| 方向 | 记录内容 |
+|------|----------|
+| 服务器运维 | Linux、systemd、Caddy、服务部署与故障排查 |
+| Kubernetes / k3s | 集群搭建、应用部署、网络、存储与日常维护 |
+| 自托管服务 | Gitea、Hugo、监控、网关、反向代理等 |
+| 网络与访问 | Tailscale、内网互联、安全访问、服务暴露 |
+| 开发环境 | Zsh、编辑器、dotfiles、CLI 工具、自动化脚本 |
+| 折腾记录 | 真实问题、排查路径、踩坑和复盘 |
+
+## 写作原则
+
+我希望这里的文章尽量做到：
+
+1. **有上下文**：说明为什么要做，而不只是贴命令。
+2. **可验证**：每个部署或配置都尽量写清楚验证方法。
+3. **可复用**：把踩坑过程沉淀成以后还能参考的记录。
+4. **注意安全**：公开文章不会暴露真实公网 IP、密钥、Token 或敏感基础设施细节。
+
+## 这个博客的定位
+
+这个博客不是为了追求更新频率，而是作为一个长期的技术沉淀仓库。
+
+如果某个问题未来可能再次遇到，就值得写下来；如果某个部署步骤能复用，就值得整理；如果某个坑让我浪费过时间，也应该记录，避免以后再踩一次。
+
+## 联系方式
+
+- Gitea：<https://git.luochen570.cn/luochen570>
+- 邮箱：<1160510664@qq.com>
--- a/content/archives.md
+++ b/content/archives.md
@@ -0,0 +1,6 @@
+---
+title: '归档'
+layout: 'archives'
+summary: '按时间线浏览全部文章'
+draft: false
+---
--- a/content/search.md
+++ b/content/search.md
@@ -0,0 +1,7 @@
+---
+title: '搜索'
+layout: 'search'
+placeholder: '搜索文章标题、标签或正文内容...'
+summary: '站内全文搜索'
+draft: false
+---
--- a/hugo.toml
+++ b/hugo.toml
@@ -1,4 +1,118 @@
 baseURL = 'https://hugo.luochen570.cn/'
 locale = 'zh_cn'
-title = 'Luochen570 Hugo Blog'
+title = '洛尘的技术笔记'
 theme = 'PaperMod'
+enableRobotsTXT = true
+enableEmoji = true
+hasCJKLanguage = true
+mainsections = ['posts']
+
+[pagination]
+pagerSize = 8
+
+[taxonomies]
+category = 'categories'
+tag = 'tags'
+series = 'series'
+
+[outputs]
+home = ['HTML', 'RSS', 'JSON']
+
+[params]
+env = 'production'
+description = '洛尘的技术笔记：记录自托管服务、Linux 运维、k3s、Tailscale、Hugo、开发环境和自动化实践。'
+author = '洛尘'
+defaultTheme = 'auto'
+ShowReadingTime = true
+ShowShareButtons = false
+ShowPostNavLinks = true
+ShowBreadCrumbs = true
+ShowCodeCopyButtons = true
+ShowRssButtonInSectionTermList = true
+ShowToc = true
+TocOpen = false
+ShowPageNums = true
+ShowWordCount = true
+ShowFullTextinRSS = false
+disableSpecial1stPost = false
+
+[params.homeInfoParams]
+Title = '你好，我是洛尘 👋'
+Content = '''
+这里记录我的自托管服务、服务器运维、k3s 集群、Tailscale 组网、Hugo 博客、终端环境和自动化实践。
+
+我希望每篇文章都尽量说明：为什么这么做、具体怎么做、怎么验证成功，以及踩过哪些坑。
+'''
+
+[[params.socialIcons]]
+name = 'github'
+title = 'Gitea'
+url = 'https://git.luochen570.cn/luochen570'
+
+[[params.socialIcons]]
+name = 'email'
+title = 'Email'
+url = 'mailto:1160510664@qq.com'
+
+[[params.socialIcons]]
+name = 'rss'
+title = 'RSS'
+url = '/index.xml'
+
+[params.assets]
+disableHLJS = true
+
+[params.fuseOpts]
+isCaseSensitive = false
+shouldSort = true
+location = 0
+distance = 1000
+threshold = 0.35
+minMatchCharLength = 1
+keys = ['title', 'permalink', 'summary', 'content']
+
+[markup]
+  [markup.goldmark]
+    [markup.goldmark.renderer]
+    unsafe = true
+  [markup.highlight]
+    noClasses = false
+    codeFences = true
+    guessSyntax = true
+    lineNos = false
+
+[menu]
+  [[menu.main]]
+  name = '首页'
+  url = '/'
+  weight = 1
+
+  [[menu.main]]
+  name = '文章'
+  url = '/posts/'
+  weight = 2
+
+  [[menu.main]]
+  name = '归档'
+  url = '/archives/'
+  weight = 3
+
+  [[menu.main]]
+  name = '标签'
+  url = '/tags/'
+  weight = 4
+
+  [[menu.main]]
+  name = '分类'
+  url = '/categories/'
+  weight = 5
+
+  [[menu.main]]
+  name = '搜索'
+  url = '/search/'
+  weight = 6
+
+  [[menu.main]]
+  name = '关于'
+  url = '/about/'
+  weight = 7