Hugo + PaperMod 博客写作完全指南

📝 创建新文章

使用 Hugo 命令创建

1
2
3
4
# 创建新文章
hugo new posts/my-article.md

# 文章会自动应用 archetypes/default.md 模板

文件命名建议

✅ 推荐：使用小写字母 + 连字符：how-to-write-hugo.md
✅ 可选：使用下划线：my_first_post.md
⚠️ 支持但不推荐：中文文件名 我的文章.md

🎯 Front Matter 配置详解

Front Matter 是文章开头的元数据部分，Hugo 支持 YAML 和 TOML 两种格式。

YAML 格式（推荐）

使用 --- 包裹，更易读，是本博客的标准格式：

1
2
3
4
5
6
7
8
9
---
title: "文章标题"
date: 2025-11-15T14:30:00+08:00
draft: false
author: "LexHsu"
categories: ["tech", "life"]
tags: ["hugo", "markdown"]
description: "文章摘要，显示在列表页和搜索结果中"
---

TOML 格式（备选）

使用 +++ 包裹：

1
2
3
4
5
6
7
8
9
+++
title = '文章标题'
date = '2025-11-15T14:30:00+08:00'
draft = false
author = 'LexHsu'
categories = ['tech', 'life']
tags = ['hugo', 'markdown']
description = '文章摘要'
+++

核心字段说明

字段	必需	说明	示例
`title`	✅	文章标题	`"我的第一篇文章"`
`date`	✅	发布日期时间	`2025-11-15T14:30:00+08:00`
`draft`	✅	是否为草稿	`false` 发布, `true` 草稿
`author`	❌	作者名称	`"LexHsu"`
`categories`	❌	分类（数组）	`["tech", "tutorial"]`
`tags`	❌	标签（数组）	`["hugo", "markdown"]`
`description`	❌	文章摘要	显示在列表和搜索中

⚠️ 重要提示：

新创建的文章默认 draft: true，必须改为 false 才能发布
日期格式使用 ISO 8601，时区为 +08:00（中国标准时间）
categories 和 tags 会自动生成分类页和标签页

🎨 PaperMod 主题特有配置

封面图片配置

在 Front Matter 中添加封面图：

1
2
3
4
5
6
7
8
9
---
title: "文章标题"
cover:
    image: "/images/my-article/cover.jpg"
    alt: "封面图片描述"
    caption: "图片说明文字"
    relative: false  # 使用绝对路径
    hidden: false    # 列表页显示封面
---

封面图片选项：

参数	说明	默认值
`image`	图片路径	-
`alt`	图片 alt 文本	-
`caption`	图片说明（显示在图片下方）	-
`relative`	是否使用相对路径	`false`
`hidden`	在列表页隐藏封面	`false`
`hiddenInList`	仅在列表页隐藏	`false`
`hiddenInSingle`	仅在文章页隐藏	`false`

文章目录（TOC）控制

1
2
3
4
5
---
title: "文章标题"
ShowToc: true           # 显示目录
TocOpen: false          # 默认折叠目录
---

禁用特定功能

1
2
3
4
5
6
7
8
---
title: "文章标题"
ShowBreadCrumbs: false  # 隐藏面包屑导航
ShowReadingTime: false  # 隐藏阅读时间
ShowShareButtons: false # 隐藏分享按钮
ShowPostNavLinks: false # 隐藏上一篇/下一篇导航
comments: false         # 禁用评论
---

文章权重（置顶）

1
2
3
4
---
title: "重要文章"
weight: 1  # 数字越小越靠前，可用于置顶
---

SEO 相关配置

1
2
3
4
5
6
---
title: "文章标题"
description: "文章描述，用于 SEO"
keywords: ["关键词1", "关键词2"]
canonicalURL: "https://allenhsu6.github.io/posts/hugo-writing-guide/"
---

📖 Markdown 基础语法

标题

1
2
3
4
5
6
# 一级标题
## 二级标题
### 三级标题
#### 四级标题
##### 五级标题
###### 六级标题

文本样式

1
2
3
4
5
**粗体文本**
*斜体文本*
***粗斜体***
~~删除线~~
`行内代码`

效果：粗体斜体 粗斜体 ~~删除线~~ code

列表

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
无序列表：
- 项目 1
- 项目 2
  - 子项目 2.1
  - 子项目 2.2

有序列表：
1. 第一项
2. 第二项
3. 第三项

任务列表：
- [x] 已完成任务
- [ ] 待完成任务

链接和图片

1
2
3
4
5
[链接文本](https://example.com)
[带标题的链接](https://example.com "鼠标悬停显示")

![图片描述](/images/example.png)
![图片带链接](/images/example.png "图片标题")

引用

1
2
3
4
> 这是引用文字
> 可以多行
>
> > 嵌套引用

这是引用文字可以多行

分隔线

1
2
3
4
5
---
或者
***
或者
___

💻 代码块（带语法高亮）

行内代码

使用反引号包裹：`code`

代码块

使用三个反引号 + 语言标识：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
```python
def hello_world():
    print("Hello, Hugo!")
    return True
```

```javascript
const greeting = (name) => {
    console.log(`Hello, ${name}!`);
};
```

```bash
hugo server -D
git commit -m "Add new post"
```

支持的语言：python, javascript, go, java, bash, yaml, json, markdown 等

主题配置的代码高亮特性（已在 hugo.yml 中配置）：

✅ 自动语法高亮（Monokai 主题）
✅ 显示行号
✅ 自动猜测语法
✅ 代码围栏支持

🧮 数学公式（MathJax）

本博客已启用 MathJax 2.7.3，支持 LaTeX 数学公式。

内联公式

使用 $...$ 包裹：

1
2
3
这是内联公式 $E = mc^2$，爱因斯坦的质能方程。

变量定义：$d_h$ 表示每个注意力头的嵌入维度。

效果：这是内联公式 $E = mc^2$，爱因斯坦的质能方程。

块级公式

使用 $$...$$ 包裹：

1
2
3
$$
o_{t, i} = \sum_{j=1}^{t} \text{Softmax}_j\left(\frac{q_{t, i}k_{j, i}^T}{\sqrt{d_h}}\right)v_{j, i}
$$

效果展示：

$$ o_{t, i} = \sum_{j=1}^{t} \text{Softmax}j\left(\frac{q{t, i}k_{j, i}^T}{\sqrt{d_h}}\right)v_{j, i} $$

常用数学符号

符号	代码	符号	代码
$\alpha$	`\alpha`	$\beta$	`\beta`
$\sum$	`\sum`	$\prod$	`\prod`
$\int$	`\int`	$\partial$	`\partial`
$\infty$	`\infty`	$\approx$	`\approx`
$\leq$	`\leq`	$\geq$	`\geq`
$\frac{a}{b}$	`\frac{a}{b}`	$\sqrt{x}$	`\sqrt{x}`

矩阵和方程组

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
$$
\begin{bmatrix}
a & b \\
c & d
\end{bmatrix}
$$

$$
\begin{cases}
x + y = 5 \\
x - y = 1
\end{cases}
$$

MathJax 配置特性（已在 layouts/partials/mathjax.html 中配置）：

✅ 支持 AMS 数学扩展
✅ 自动公式编号
✅ Times New Roman 字体
✅ 支持 \[...\] 和 $...$ 语法

📊 表格

1
2
3
4
5
6
7
8
9
| 列1 | 列2 | 列3 |
|-----|-----|-----|
| 内容1 | 内容2 | 内容3 |
| 数据A | 数据B | 数据C |

对齐方式：
| 左对齐 | 居中对齐 | 右对齐 |
|:-------|:--------:|-------:|
| Left   | Center   | Right  |

效果：

符号	说明	维度
$q_t$	Query 向量	$d_{model}$
$k_t$	Key 向量	$d_{model}$
$v_t$	Value 向量	$d_{model}$

🎁 PaperMod 主题 Shortcodes

折叠内容块（Collapse）

1
2
3
4
5
6
7
8
{{< collapse summary="点击展开详细内容" openByDefault=false >}}
这里是折叠的内容，可以放置：
- 长篇代码
- 详细说明
- 补充资料

默认是折叠状态，点击才展开。
{{< /collapse >}}

点击展开示例

这是折叠内容的示例！

你可以在这里放置：

📚 详细的技术文档
💻 长篇代码示例
📖 补充阅读材料
🔍 调试信息

参数说明：

summary: 折叠块的标题文本
openByDefault: true 默认展开，false 默认折叠

增强图片（Figure）

1
2
3
4
5
6
7
8
9
{{< figure 
    src="/images/example.png" 
    alt="图片描述" 
    caption="这是图片说明文字"
    attr="图片来源"
    attrlink="https://example.com"
    align="center"
    width="600px"
>}}

参数说明：

src: 图片路径（必需）
alt: Alt 文本
caption: 图片说明（显示在图片下方）
attr: 图片属性/来源
attrlink: 属性链接
align: 对齐方式（left/center/right）
width/height: 尺寸控制

原始 HTML（RawHTML）

⚠️ 注意：当前博客配置 goldmark.renderer.unsafe: false，不支持直接写 HTML，需使用 shortcode：

1
2
3
4
5
6
{{< rawhtml >}}
<div style="border: 2px solid #f00; padding: 10px;">
  <p>自定义 HTML 内容</p>
  <button onclick="alert('Hello!')">点击我</button>
</div>
{{< /rawhtml >}}

行内图片（InTextImg）

在文本中插入小图标：

1
这是文本 {{< inTextImg url="/images/icon.png" height="20" >}} 继续文本

🖼️ 图片资源管理

在文章中引用图片

1
2
3
4
5
6
7
8
9
# 方式 1：标准 Markdown
![图片描述](/images/article-name/screenshot1.png)

# 方式 2：使用 figure shortcode（推荐）
{{< figure 
    src="/images/article-name/screenshot1.png" 
    alt="截图说明"
    caption="图 1: 系统架构图"
>}}

图片路径规则

✅ 绝对路径（推荐）：/images/article-name/image.png
- 从 static/ 目录开始，/images/ 对应 static/images/
❌ 相对路径：不推荐，可能导致路径错误

图片快捷粘贴

如果使用支持的编辑器（如 VS Code + Markdown 插件）：

macOS: Option + Command + V
Windows/Linux: Ctrl + Alt + V

自动保存到指定目录并插入引用。

🚀 本地预览与发布

本地开发服务器

1
2
3
4
# 启动预览服务器（包括草稿）
hugo server -D

# 访问 http://localhost:1313

服务器特性：

✅ 实时热重载
✅ 显示草稿文章（-D 参数）
✅ 自动检测文件变化

不包含草稿预览

1
2
# 只预览已发布文章（draft: false）
hugo server

构建静态站点

1
2
3
4
5
# 生成静态文件到 public/ 目录
hugo

# 清理并重新构建
hugo --cleanDestinationDir

✅ 发布检查清单

在提交文章前，请确认：

draft: false - 已设置为发布状态
title - 标题准确且吸引人
date - 日期时间正确（格式：2025-11-15T14:30:00+08:00）
categories 和 tags - 已添加合适的分类和标签
description - 写了文章摘要（有助于 SEO）
图片路径正确 - 所有图片都能正常显示
数学公式渲染 - 公式显示正确
代码高亮 - 代码块语言标识正确
链接有效 - 外部链接可访问
本地预览无误 - hugo server 检查效果

🔧 常见问题与解决方案

1. 文章不显示在首页

原因：

draft: true 未改为 false
日期设置为未来时间

解决：

1
2
draft: false
date: 2025-11-15T14:30:00+08:00  # 确保时间不晚于当前

2. 数学公式不渲染

检查：

是否使用了正确的分隔符 $...$ 或 $$...$$
特殊字符是否需要转义（如 \_ \{ \}）

示例：

1
2
正确：$E = mc^2$
错误：$ E = mc^2 $  # 分隔符与内容之间不要有空格

3. 图片无法显示

检查清单：

图片路径以 / 开头（绝对路径）
图片存放在 static/images/ 目录下
文件名大小写匹配（Linux 系统区分大小写）
图片格式支持（jpg, png, gif, svg, webp）

4. 中文标题锚点问题

PaperMod 主题支持中文标题自动生成锚点：

1
2
3
## 中文标题

链接到标题：[跳转](#中文标题)

5. 想使用原始 HTML

方法 1：使用 rawhtml shortcode

1
2
3
{{< rawhtml >}}
<div>HTML 内容</div>
{{< /rawhtml >}}

方法 2：修改配置（不推荐，有安全风险）

1
2
3
4
5
# hugo.yml
markup:
  goldmark:
    renderer:
      unsafe: true  # 允许原始 HTML

🔄 自动化部署流程

本博客的发布流程完全自动化：

编写文章 - 在 my_blog 私有仓库的 content/posts/ 目录编写
Git 提交 - git add . && git commit -m "Add new post" && git push
自动构建 - GitHub Actions 检测到推送，自动运行 Hugo 构建
自动部署 - 构建的静态文件推送到 allenhsu6.github.io 仓库
自动发布 - GitHub Pages 自动部署到 https://allenhsu6.github.io

无需手动操作：推送代码后 1-2 分钟即可在线访问！

📚 扩展资源

官方文档

数学公式

本博客配置

Hugo 版本：v0.152.2
主题：PaperMod
代码高亮：Monokai
数学公式：MathJax 2.7.3

💡 写作技巧建议

使用有意义的标题 - 清晰的层级结构（H2、H3、H4）
添加目录 - 长文章设置 ShowToc: true
使用 emoji - 适当使用表情符号增强可读性 ✨
代码注释 - 代码块添加语言标识以启用高亮
图文并茂 - 使用图片、表格、公式丰富内容
折叠长内容 - 使用 collapse shortcode 折叠次要信息
SEO 优化 - 填写 description、keywords，使用有意义的 URL
分类合理 - categories 用于大分类，tags 用于细粒度标签

🎉 开始创作

现在你已经掌握了所有必要的知识，开始创作你的第一篇文章吧！

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
# 创建新文章
hugo new posts/my-awesome-post.md

# 编辑文章
# 设置 draft: false

# 本地预览
hugo server -D

# 提交发布
git add .
git commit -m "Add: my awesome post"
git push

祝写作愉快！✍️

📝 创建新文章#

使用 Hugo 命令创建#

文件命名建议#

🎯 Front Matter 配置详解#

YAML 格式（推荐）#

TOML 格式（备选）#

核心字段说明#

🎨 PaperMod 主题特有配置#

封面图片配置#

文章目录（TOC）控制#

禁用特定功能#

文章权重（置顶）#

SEO 相关配置#

📖 Markdown 基础语法#

标题#

文本样式#

列表#

链接和图片#

引用#

分隔线#

💻 代码块（带语法高亮）#

行内代码#

代码块#

🧮 数学公式（MathJax）#

内联公式#

块级公式#

常用数学符号#

矩阵和方程组#

📊 表格#

🎁 PaperMod 主题 Shortcodes#

折叠内容块（Collapse）#

增强图片（Figure）#

原始 HTML（RawHTML）#

行内图片（InTextImg）#

🖼️ 图片资源管理#

推荐的图片组织方式#

在文章中引用图片#

图片路径规则#

图片快捷粘贴#

🚀 本地预览与发布#

本地开发服务器#

不包含草稿预览#

构建静态站点#

✅ 发布检查清单#

🔧 常见问题与解决方案#

1. 文章不显示在首页#

2. 数学公式不渲染#

3. 图片无法显示#

4. 中文标题锚点问题#

5. 想使用原始 HTML#

🔄 自动化部署流程#

📚 扩展资源#

官方文档#

数学公式#

本博客配置#

💡 写作技巧建议#

🎉 开始创作#