From e0d7f07c24eb734acc66921106d63539e16257dc Mon Sep 17 00:00:00 2001 From: luochen570 <1160510664@qq.com> Date: Thu, 28 May 2026 22:50:42 +0800 Subject: [PATCH] configure homepage and site navigation --- THEME_NOTES.md | 160 ++++++++++++++++++++++++++++++++++++++++++++ content/about.md | 43 ++++++++++++ content/archives.md | 6 ++ content/search.md | 7 ++ hugo.toml | 116 +++++++++++++++++++++++++++++++- 5 files changed, 331 insertions(+), 1 deletion(-) create mode 100644 THEME_NOTES.md create mode 100644 content/about.md create mode 100644 content/archives.md create mode 100644 content/search.md diff --git a/THEME_NOTES.md b/THEME_NOTES.md new file mode 100644 index 0000000..c284160 --- /dev/null +++ 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. 不建议一开始就做大量复杂定制，先保证内容结构稳定。 diff --git a/content/about.md b/content/about.md new file mode 100644 index 0000000..6c2689c --- /dev/null +++ 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： +- 邮箱：<1160510664@qq.com> diff --git a/content/archives.md b/content/archives.md new file mode 100644 index 0000000..c8b2e3b --- /dev/null +++ b/content/archives.md @@ -0,0 +1,6 @@ +--- +title: '归档' +layout: 'archives' +summary: '按时间线浏览全部文章' +draft: false +--- diff --git a/content/search.md b/content/search.md new file mode 100644 index 0000000..f9e4eae --- /dev/null +++ b/content/search.md @@ -0,0 +1,7 @@ +--- +title: '搜索' +layout: 'search' +placeholder: '搜索文章标题、标签或正文内容...' +summary: '站内全文搜索' +draft: false +--- diff --git a/hugo.toml b/hugo.toml index 11b7cbe..840d69d 100644 --- 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