Hugo 博客使用文档

站点信息

  • 站点目录：D:\ClaudeOutput\my-site\
  • 文章目录：content\posts\
  • 配置文件：hugo.toml
  • 主题：PaperMod
  • 本地预览：http://localhost:1313/
  • GitHub 仓库：https://github.com/mr0ptimist/mr0ptimist.github.io

BAT 工具

文件功能
serve_启动预览.bat启动本地预览服务器（自动杀旧进程），含草稿，实时刷新
build_构建发布.bat构建静态文件到 public/ 目录
new-post_新建文章.bat交互式创建文章（标题、标签、分类、是否隐藏）
clean_清除输出.bat删除 public/ 目录

日常写文章流程

1. 双击 new-post_新建文章.bat → 输入标题、选标签/分类、是否隐藏
2. 编辑 content/posts/xxx.md → 写文章内容
3. 双击 serve_启动预览.bat → 浏览器打开 http://localhost:1313/ 查看效果
4. 关掉预览（关闭窗口即可）
5. git add . && git commit -m "new post" && git push → 自动部署

文章格式

+++
date = '2026-04-20T12:00:00+08:00'
draft = false
title = '文章标题'
tags = ['标签1', '标签2']
categories = ['分类']
hidden = true
+++

正文内容，支持 Markdown 语法。
  • draft = true：草稿，只在 serve -D 模式下显示
  • draft = false：正式发布
  • hidden = true：加密文章，需在导航栏输入密码后才显示

私密文章

  • 在 hugo.toml 中配置 secretPassword = '密码'
  • 文章 front matter 加 hidden = true 即可隐藏
  • 导航栏锁图标 → 弹窗输入密码 → 隐藏文章出现
  • 再次点击锁图标 → 重新锁定
  • 密码状态用 sessionStorage，关闭浏览器自动重置
  • 隐藏文章不会出现在分类、标签列表中

导航栏功能

按钮功能
锁图标解锁/锁定私密文章
箭头图标调整文章宽度和 TOC 宽度
太阳/月亮切换亮色/暗色主题

TOC（目录导航）

  • 大屏（1400px+）自动在左侧显示浮动 TOC
  • 滚动时高亮当前标题
  • 只显示一级标题和带数字编号的子标题
  • 点击箭头按钮可调整 TOC 宽度（150-400px）

部署

使用 GitHub Actions 自动部署，push 到 main 分支即可：

cd D:\ClaudeOutput\my-site
git add .
git commit -m "new post"
git push

Actions 会自动 hugo build 并部署到 GitHub Pages。

更换主题

cd D:\ClaudeOutput\my-site
git submodule add https://github.com/adityatelange/hugo-PaperMod.git themes/PaperMod

然后修改 hugo.toml：theme = 'PaperMod'

常见问题

  • 端口被占用：serve.bat 自动杀旧 hugo 进程
  • 文章不显示：检查 draft 是否为 false，日期是否在未来（需 buildFuture = true）
  • 样式没更新：Ctrl+F5 强制刷新
  • GitHub 推送失败：检查网络，国内可能需要代理
  • 新文章不在列表：确保 date 不是未来日期，或 hugo.toml 已配 buildFuture = true