从零搭建 Hugo + PaperMod 博客之二： 新建文章与撰写

前言

到目前为止，本站点基础环境已就绪。本篇聚焦博客内容生产的核心环节：如何新建文章、理解文章配置、撰写正文并预览效果。

目标：掌握 hugo new 命令、Front Matter 配置、模板自定义，实现「命令创建 → 编辑内容 → 本地预览」的完整写作流程。

一、新建文章：命令详解

1.1 基本命令格式

hugo new posts/first-post.md

命令各部分含义：

执行后，Hugo 会在 content/posts/ 目录下生成 first-post.md 文件。

提示：若 posts 目录不存在，Hugo 会自动创建。

1.2 生成路径说明

myblog/
├── content/
│   └── posts/
│       └── first-post.md   ← 新生成的文章
├── archetypes/
│   └── default.md          ← 文章模板（后文详解）
└── hugo.toml

文章源文件始终位于 content/ 目录下，构建后输出至 public/。

二、Front Matter：文章元数据配置

2.1 默认生成内容

新建文章后，content/posts/first-post.md 默认内容如下（Hugo 0.161.1 默认使用 TOML 格式）：

+++
date = '2026-06-02T17:53:36+08:00'
draft = true
title = 'First Post'
+++

• +++ ... +++ 是 TOML 格式的 Front Matter 分隔符（也可用 --- 表示 YAML）
• title：文章标题，默认由文件名自动转换（first-post.md → First Post）
• date：文章创建时间，格式为 RFC3339
• draft = true：草稿状态，预览时需加 -D 参数才能显示

2.2 常用配置项说明

在 Front Matter 中可添加以下字段控制文章行为：

+++
title = '文章标题'
date = 2026-05-31T12:00:00+08:00
lastmod = 2026-06-01T10:00:00+08:00  # 最后修改时间（可选）
draft = false                          # 是否草稿：true=隐藏，false=发布
series = ['博客搭建']                  # 所属系列
categories = ['Tech Notes']           # 分类
tags = ['Hugo', 'PaperMod']           # 标签
description = '文章摘要，用于首页/列表页展示'
+++

配置优先级：文章 Front Matter > 全局 hugo.toml 配置。即文章内设置会覆盖全局默认值。

2.3 TOML 与 YAML 语法对比

Hugo 支持两种 Front Matter 格式，可根据偏好选择：

示例：同一配置的 YAML 写法

---
title: "文章标题"
date: 2026-05-31T12:00:00+08:00
draft: false
series:
  - 博客搭建
categories:
  - Tech Notes
tags:
  - Hugo
  - PaperMod
---

建议：项目内保持统一格式。若团队协作文档，YAML 可读性略优；若追求解析速度，TOML 略快（差异可忽略）。

三、修改标题与撰写正文

3.1 修改标题

直接编辑 Front Matter 中的 title 字段：

+++
title = '从零搭建 Hugo + PaperMod 博客之二：新建文章与撰写'
+++

注意：标题中的单引号需转义或改用双引号，如 title = "It's easy"。

3.2 撰写正文

Front Matter 结束后（即 +++ 或 --- 之后），即可开始撰写 Markdown 正文：

+++
title = '示例文章'
date = 2026-05-31T12:00:00+08:00
draft = false
+++

## 正文开始

这里是文章内容，支持标准 Markdown 语法：

- 列表项
- **加粗**、*斜体*、`行内代码`

### 代码块示例

```cmd
echo Hello Hugo
```

### 链接与图片

- 链接：[Hugo 官网](https://gohugo.io)
- 图片：`![替代文本](/images/photo.jpg)`

提示：正文中的代码块需用三反引号包裹，并指定语言标识（如 cmd、toml），才能启用高亮与复制功能。

四、自定义文章模板：archetypes/default.md

4.1 模板作用

archetypes/default.md 是 hugo new 命令的默认模板。修改此文件可统一新文章的 Front Matter 结构，减少重复配置,可根据自己的偏好进行个性化设置。

4.2 示例配置（适配本系列）

编辑 archetypes/default.md，替换为以下内容：

+++
date = '{{ .Date }}'
# lastmod = 
draft = false
title = '{{ replace .File.ContentBaseName "-" " " | title }}'
series = []
categories = []
tags = []
+++

字段说明：

技巧：# lastmod = 以注释形式保留，需要时取消注释并填写即可。

4.3 创建特定类型的模板（可选）

若需为不同内容类型（如 docs、notes）设置不同模板：

:: 创建 docs 类型模板:在 archetypes 内创建 docs.md并自定义模板内容。

:: 使用模板新建文章 hugo new docs/api-reference.md

---

## 五、其他注意事项

### 5.1 文件命名规范

- 使用小写字母、数字、短横线（`-`）
- 避免空格、中文、特殊字符（如 `?` `*` `:`）
- 示例：`2026-05-31-hugo-new-command.md`

> 原因：文件名会直接影响 URL 路径，不规范命名可能导致链接失效或部署问题。

### 5.2 分类与标签填写建议

- `categories`：宏观分类，建议 1~2 个，如 `Tech Notes`、`Life`
- `tags`：细粒度关键词，可多个，如 `Hugo`、`PaperMod`、`Windows`
- `series`：系列文章标识，如 `博客搭建`，便于读者连续阅读

### 5.3 草稿管理

- 开发阶段：保留 `draft = true`，预览时加 `-D` 参数
- 发布前：改为 `draft = false`，或构建时不加 `-D`

```cmd
:: 预览包含草稿的文章
hugo server -D -F

:: 生产构建（自动排除草稿）
hugo --minify --gc

5.4 文章描述（description）的作用

• SEO 优化：搜索引擎抓取 Description 作为页面描述
• 在 PaperMod 主题中，description 还有一个前端可见的作用：在单页头部（single.html）或列表页头部（如 tags/_index.md），它会显示为标题下方的灰色副标题

5.5 文章摘要（summary）的作用

• 首页/列表页显示文章摘要，提升可读性
• 填写建议：50~120 字，概括核心内容，避免与标题重复
• 若留空，则默认抓取正文前 70 左右字/词， hugo 会根据实际内容在适当位置截断
• 还可以在正文任意位置添加 <!--more​--> 分隔符标记，截取文章摘要，这种方式优先级最高。其次是指定 summary，最后 hugo 才会默认抓取正文前一定数量字词
• <!--​more--> 必须严格书写，前后可以有空行，但 more 单词前后不能有空格

5.6 文章摘要（summary）与描述(description)的区别

六、本地预览：实时查看效果

6.1 启动开发服务器

:: 在项目根目录执行
hugo server -D -F --disableFastRender

参数说明：

6.2 访问与调试

• 浏览器打开：http://localhost:1313
• 屏幕阅读器用户：直接按字母 H 导航至文章标题，确认加载成功
• 修改 .md 文件后保存，浏览器自动刷新（无需手动重启）

提示：若修改 hugo.toml 或主题文件，需重启 hugo server 才能生效。

七、小结

本篇核心要点：

1. hugo new posts/xxx.md 创建文章，文件位于 content/posts/
2. Front Matter 支持 TOML/YAML，文章配置优先于全局配置
3. 修改 archetypes/default.md 统一新文章模板
4. 正文撰写遵循标准 Markdown，代码块需三反引号 + 语言标识
5. hugo server -D -F 实时预览，支持草稿与未来日期文章

参考资源

• Hugo 内容管理文档：https://gohugo.io/content-management/
• Front Matter 说明：https://gohugo.io/content-management/front-matter/
• Archetypes 自定义：https://gohugo.io/content-management/archetypes/
• TOML 语法指南：https://toml.io/
• YAML 语法速查：https://yaml.org/