0003 - Hugo博客进阶配置与使用指南

前言

本文汇总了 Hugo 博客的进阶配置需求，包括时间显示、主题用法、手动上传方法以及文章加密等功能。

一、添加发布时间和最后修改时间

1.1 配置文章显示时间

Hugo 默认支持文章时间显示，只需在文章头部添加 date 字段：

---
title: "文章标题"
date: 2026-03-07
lastmod: 2026-03-07  # 最后修改时间（可选）
---

1.2 在主题中显示时间

PaperMod 主题默认会显示发布时间。如需自定义时间格式，在 hugo.toml 中配置：

[params]
dateFormat = "2006-01-02"

二、Hugo 常规用法汇总

2.1 创建新文章

# 方法1：使用 Hugo 命令
hugo new posts/文章标题.md

# 方法2：手动创建文件
# 在 content/posts/ 目录下创建 .md 文件

2.2 文章 Front Matter 配置

---
title: "文章标题"
date: 2026-03-07
lastmod: 2026-03-07
draft: false
math: true
hideSummary: true
tags: ["标签1", "标签2"]
categories: ["分类"]
---

2.3 本地预览

# 启动本地服务器
hugo server -D

# 访问 http://localhost:1313/

2.4 构建网站

# 构建静态网站
hugo

# 构建结果在 public/ 目录

2.5 部署到 GitHub Pages

# 进入 public 目录
cd public

# 初始化 Git（首次）
git init
git branch -M main

# 添加远程仓库
git remote add origin https://github.com/Wubajie/wubajie.github.io.git

# 提交并推送
git add .
git commit -m "更新博客"
git push origin main

三、PaperMod 主题常规用法

3.1 主题配置参数

在 hugo.toml 中配置：

[params]
# 首页信息
[params.homeInfoParams]
Title = "Hi there 👋"
Content = "Welcome to my blog"

# 社交图标
[[params.socialIcons]]
name = "github"
url = "https://github.com/Wubajie"

[[params.socialIcons]]
name = "email"
url = "mailto:wwssqj@gmail.com"

# 资源配置
[params.assets]
disableHLJS = true
favicon = "/favicon.ico"
favicon16x16 = "/favicon-16x16.png"
favicon32x32 = "/favicon-32x32.png"

# 封面图配置
[params.cover]
hidden = true
hiddenInList = true
hiddenInSingle = true

# 日期格式
dateFormat = "2006-01-02"

3.2 文章参数

---
# 隐藏封面图
cover:
    hidden: true

# 隐藏元数据
hideMeta: false

# 显示目录
ShowToc: true
TocOpen: true
---

3.3 自定义样式

在 static/css/custom.css 中添加自定义样式：

body {
    font-family: "Microsoft YaHei", sans-serif;
}

然后在 layouts/partials/extend_head.html 中引用：

<link rel="stylesheet" href="/css/custom.css">

四、不通过 Trae 手动上传 MD 文档

4.1 方法一：使用 Git 命令行

# 1. 创建新文章
cd ~/Documents/blog_wqq/my-tech-blog/content/posts
vim 新文章.md

# 2. 编辑文章内容
# 使用任意编辑器编写 Markdown

# 3. 构建网站
cd ~/Documents/blog_wqq/my-tech-blog
hugo

# 4. 推送到 GitHub
cd public
git add .
git commit -m "添加新文章"
git push origin main

4.2 方法二：使用 GitHub 网页

访问 https://github.com/Wubajie/wubajie.github.io
点击 Add file → Create new file
在 content/posts/ 目录下创建新文件
编写内容后点击 Commit changes

注意：此方法需要手动运行 hugo 构建命令，或者等待 GitHub Actions 自动构建。

4.3 方法三：使用 VS Code + GitHub 插件

安装 VS Code
安装 GitLens 和 GitHub Pull Requests 插件
克隆仓库到本地
在 VS Code 中编辑文章
使用插件提交和推送

五、为笔记加锁（密码保护）

5.1 方法一：使用 Hugo 的 draft 功能

将文章设置为草稿状态：

---
title: "私密文章"
date: 2026-03-07
draft: true  # 草稿状态，不会发布
---

缺点：本地预览时需要添加 -D 参数：hugo server -D

5.2 方法二：使用自定义前端保护

创建 layouts/partials/extend_head.html：

{{ if .Params.password }}
<script>
  const password = "{{ .Params.password }}";
  const userPassword = prompt("请输入密码访问此文章：");
  
  if (userPassword !== password) {
    document.body.innerHTML = "<h1>密码错误，无法访问</h1>";
    throw new Error("Password incorrect");
  }
</script>
{{ end }}

在文章头部添加密码：

---
title: "私密文章"
password: "your-password"
---

5.3 方法三：使用 GitHub Pages 私有仓库

将仓库设置为私有：

访问 https://github.com/Wubajie/wubajie.github.io/settings
在 Danger Zone 点击 Change visibility
选择 Private

缺点：私有仓库的 GitHub Pages 需要升级到付费计划。

5.4 方法四：使用第三方服务

使用如 Auth0、Firebase Auth 等服务实现完整的身份验证系统。

六、完整工作流程总结

6.1 日常发布流程

# 1. 创建文章
cd ~/Documents/blog_wqq/my-tech-blog
hugo new posts/新文章.md

# 2. 编辑文章
# 使用任意编辑器打开 content/posts/新文章.md

# 3. 本地预览（可选）
hugo server -D
# 访问 http://localhost:1313/

# 4. 构建并部署
hugo
cd public
git add .
git commit -m "发布新文章"
git push origin main

6.2 文章编号规范

建议使用三位数编号：

0001-矩阵方程与向量化最小二乘.md
0002-Hugo博客搭建完整记录.md
0003-Hugo博客进阶配置与使用指南.md

七、常用命令速查

命令	说明
`hugo new posts/文章.md`	创建新文章
`hugo server -D`	启动本地预览服务器
`hugo`	构建静态网站
`hugo --cleanDestinationDir`	清理后构建
`hugo config`	查看配置信息

八、问题排查

8.1 文章不显示

检查 draft 是否为 false
检查日期是否为未来时间
检查文件是否在 content/posts/ 目录

8.2 样式不生效

清理浏览器缓存
运行 hugo --cleanDestinationDir
检查 static/ 目录下的文件

8.3 数学公式不渲染

检查文章头部是否有 math: true
检查 layouts/partials/extend_head.html 是否存在

九、后续优化建议

添加评论系统（如 Giscus、Utterances）
集成 Google Analytics
添加搜索功能
优化移动端显示
添加 RSS 订阅

十、参考资源

Hugo 官方文档：https://gohugo.io/documentation/
PaperMod 主题文档：https://github.com/adityatelange/hugo-PaperMod/wiki
Markdown 语法：https://www.markdownguide.org/

结语

本文汇总了 Hugo 博客的进阶配置和使用方法。通过这些配置，您可以：

显示文章的发布和修改时间
灵活使用 PaperMod 主题
不依赖 Trae 手动上传文章
为敏感笔记添加密码保护

希望这篇指南能帮助您更好地管理个人博客！

前言#

一、添加发布时间和最后修改时间#

1.1 配置文章显示时间#

1.2 在主题中显示时间#

二、Hugo 常规用法汇总#

2.1 创建新文章#

2.2 文章 Front Matter 配置#

2.3 本地预览#

2.4 构建网站#

2.5 部署到 GitHub Pages#

三、PaperMod 主题常规用法#

3.1 主题配置参数#

3.2 文章参数#

3.3 自定义样式#

四、不通过 Trae 手动上传 MD 文档#

4.1 方法一：使用 Git 命令行#

4.2 方法二：使用 GitHub 网页#

4.3 方法三：使用 VS Code + GitHub 插件#

五、为笔记加锁（密码保护）#

5.1 方法一：使用 Hugo 的 draft 功能#

5.2 方法二：使用自定义前端保护#

5.3 方法三：使用 GitHub Pages 私有仓库#

5.4 方法四：使用第三方服务#

六、完整工作流程总结#

6.1 日常发布流程#

6.2 文章编号规范#

七、常用命令速查#

八、问题排查#

8.1 文章不显示#

8.2 样式不生效#

8.3 数学公式不渲染#

九、后续优化建议#

十、参考资源#

结语#

前言