Hugo + PaperMod 配置指南：从零到可用

Sat, 28 Feb 2026 18:00:00 +0800

本文基于本站的实际配置，记录 Hugo + PaperMod 主题的核心配置项和常见操作。 Hugo 版本：0.157.0 | 主题：PaperMod

1. 项目初始化

# 创建站点
hugo new site blog
cd blog

# 安装 PaperMod 主题（作为 Git Submodule）
git init
git submodule add https://github.com/adityatelange/hugo-PaperMod.git themes/PaperMod

然后编辑根目录下的 hugo.toml（Hugo 0.110+ 默认用 toml，旧版用 config.yaml）。

2. hugo.toml 逐项解读

以下是本站完整配置，每项都有注释：

# --- 基础信息 ---
baseURL = 'https://sharonzhou.site/'   # 你的域名，末尾带 /
languageCode = 'zh-cn'                  # 语言代码，影响 HTML lang 属性
title = 'Sharon 的博客'                # 站点标题，显示在浏览器标签页
theme = 'PaperMod'                      # 主题名，对应 themes/ 下的目录名

# 启用 Git 信息：自动从 git commit 读取文章的创建/修改时间
enableGitInfo = true
# 构建未来日期的文章（默认 false，会导致未来日期的文章不显示）
buildFuture = true
# 列表页每页显示的文章数量
paginate = 20

# --- Front Matter 日期策略 ---
[frontmatter]
date = ['date', ':git']     # 文章日期：优先用 front matter 里的 date，没有则取 git 首次提交时间
lastmod = [':git']           # 最后修改时间：直接取 git 最近提交时间

# --- 输出格式 ---
[outputs]
home = ["HTML", "RSS", "JSON"]   # 首页生成 HTML + RSS + JSON（JSON 是搜索功能必需的）

# --- 站点参数 ---
# 注意：author 必须写成字符串，不能用 [params.author] 表格格式
# 否则页面会显示 map[name:sharon]
[params]
env = "production"                  # 启用 OpenGraph / Twitter Card 等 SEO meta
description = "个人技术博客，记录 AI、建站与方法论"
author = "Sharon"
defaultTheme = "auto"               # 主题模式：auto（跟随系统）/ light / dark
mainSections = ["posts", "ai-daily", "thoughts"]  # 归档页和首页显示哪些 Section
ShowReadingTime = true               # 显示预计阅读时间
ShowPostNavLinks = true              # 文章底部显示「上一篇/下一篇」导航
ShowBreadCrumbs = true               # 显示面包屑导航（Home » Posts » 文章名）
ShowShareButtons = false             # 不显示分享按钮
ShowCodeCopyButtons = true           # 代码块显示一键复制按钮
ShowToc = true                       # 文章详情页显示目录（Table of Contents）
TocOpen = true                       # TOC 默认展开
comments = true                      # 启用评论（需要配合评论系统组件）
hideAuthor = true                    # 隐藏文章 meta 中的作者名

# --- 导航栏 Logo ---
[params.label]
icon = "/logo.png"               # 放在 static/logo.png，显示在导航栏左侧
iconHeight = 30                   # logo 高度（px）

# --- 首页 Welcome 区域 ---
[params.homeInfoParams]
Title = "Welcome"                     # 首页大标题
Content = "写作，坐在椅子前的艺术"     # 首页副标题/描述

# --- 导航菜单 ---
# weight 决定显示顺序，数字越小越靠前
[[menus.main]]
name = "文章"
url = "/posts/"
weight = 1

[[menus.main]]
name = "AI 日报"
url = "/ai-daily/"
weight = 2

[[menus.main]]
name = "想法"
url = "/thoughts/"
weight = 3

[[menus.main]]
name = "归档"
url = "/archives/"
weight = 4

[[menus.main]]
name = "搜索"
url = "/search/"
weight = 5

[[menus.main]]
name = "关于"
url = "/about/"
weight = 6

# --- 代码高亮 ---
[markup.highlight]
noClasses = false       # 输出 CSS class 而非内联 style，便于自定义颜色

# --- Goldmark 渲染器 ---
[markup.goldmark.renderer]
unsafe = true           # 允许 Markdown 中的 raw HTML

3. 新建内容板块（Section）

Hugo 用 content/ 下的子目录来组织不同板块，每个子目录就是一个 Section，有独立的列表页。

建站 on Sharon 的博客

Hugo + PaperMod 配置指南：从零到可用

1. 项目初始化

2. hugo.toml 逐项解读

3. 新建内容板块（Section）