Hugo 静态网站构建实战手册

内容管理

学习 Hugo 的 Front Matter、栏目、分类标签、页面资源、短代码和中文内容写作组织方式

内容管理

Hugo 的内容通常使用 Markdown 编写，放在 content/ 目录中。内容管理的核心是三件事：把文件放在合适的栏目，写好 Front Matter，用清晰的分类和资源组织方式长期维护。

内容文件类型

Hugo 支持多种内容格式：

格式扩展名适用场景
Markdown.md、.markdown博客、文档、笔记，最常用
HTML.html需要完整控制 HTML 的页面
AsciiDoc.adoc复杂技术文档
reStructuredText.rstPython 文档生态
Org Mode.orgEmacs 用户

日常建站优先使用 Markdown。

Front Matter

Front Matter 是文件顶部的元数据。Hugo 支持 YAML、TOML、JSON 三种写法。

YAML 写法

---
title: "Hugo 内容管理"
date: 2026-06-10T10:00:00+08:00
draft: false
description: "学习 Hugo 内容文件、分类和页面资源"
categories: ["Hugo"]
tags: ["内容管理", "Markdown"]
---

TOML 写法

+++
title = 'Hugo 内容管理'
date = 2026-06-10T10:00:00+08:00
draft = false
description = '学习 Hugo 内容文件、分类和页面资源'
categories = ['Hugo']
tags = ['内容管理', 'Markdown']
+++

本站文档通常使用 YAML 风格，和大多数中文教程一致。

常用 Front Matter 字段

字段作用示例
title页面标题"快速开始"
date发布日期2026-06-10T10:00:00+08:00
lastmod最后修改时间2026-06-11
draft是否草稿true
description页面描述，常用于 SEO"Hugo 入门教程"
slugURL 片段"hugo-guide"
weight排序权重10
categories分类["Hugo"]
tags标签["博客", "静态网站"]
series系列["Hugo 实战"]
aliases旧链接跳转["/old-url/"]
featured_image封面图"/images/cover.jpg"

具体字段还取决于主题。主题说明中列出的参数，通常也写在 Front Matter 中。

创建内容

推荐使用 Hugo 命令创建内容，这样会自动套用 archetype：

hugo new content posts/hello-hugo.md
hugo new content docs/guide/installation.md
hugo new content about.md

如果你手动创建 Markdown，也可以正常工作，只要 Front Matter 写对即可。

栏目与 Section

content/ 下的一级目录通常就是 Section：

content/
├── posts/
├── notes/
├── docs/
└── good-things/

对应 URL：

/posts/
/notes/
/docs/
/good-things/

Hugo 会根据 Section 查找模板。例如 content/posts/hello.md 通常会使用 layouts/posts/single.html 或 layouts/_default/single.html。

列表页内容

栏目首页使用 _index.md：

content/posts/_index.md

示例：

---
title: "文章"
description: "技术、生活和长期学习记录"
weight: 1
---

# 文章

这里是我的博客文章列表。

主题通常会把 _index.md 的内容显示在列表页顶部。

页面排序

文档类页面常用 weight 控制顺序：

---
title: "安装 Hugo"
weight: 2
---

常见排序规则：

  • 文档教程：使用 weight
  • 博客文章：使用 date 倒序
  • 导航菜单：使用菜单项 weight

模板中可以这样排序：

{{ range .Pages.ByWeight }}
  <a href="{{ .RelPermalink }}">{{ .Title }}</a>
{{ end }}

草稿、未来内容和过期内容

草稿：

draft: true

未来发布日期：

date: 2030-01-01T10:00:00+08:00

过期时间：

expiryDate: 2026-12-31T23:59:59+08:00

开发时显示：

hugo server -D -F -E

对应含义：

  • -D 显示草稿
  • -F 显示未来内容
  • -E 显示过期内容

正式构建默认不包含这些内容。

分类与标签

分类适合少量、稳定、互斥或半互斥的主题；标签适合更细、更自由的关键词。

推荐做法：

categories: ["技术"]
tags: ["Hugo", "静态网站", "Markdown"]

不要把分类和标签都写得太碎。长期维护时，分类建议控制在 5 到 12 个以内，标签可以更灵活。

Page Bundles 管理资源

当文章有封面图、图集、附件时，建议使用 Page Bundle：

content/posts/hugo-image-demo/
├── index.md
├── cover.jpg
├── step-1.png
└── demo.zip

内容中引用同目录资源：

![封面](cover.jpg)

[下载示例文件](demo.zip)

模板中处理封面：

{{ with .Resources.GetMatch "cover.*" }}
  {{ $cover := .Fill "1200x630 webp" }}
  <img src="{{ $cover.RelPermalink }}" alt="{{ $.Title }}">
{{ end }}

页面资源跟随文章移动，长期维护更不容易乱。

短代码 Shortcodes

短代码用于在 Markdown 中插入可复用组件。Hugo 内置了一些短代码，主题也可能提供自己的短代码。

常见用法：

{{< figure src="cover.jpg" title="封面图" >}}

自定义短代码放在：

layouts/shortcodes/notice.html

示例：

<div class="notice notice-{{ .Get "type" | default "info" }}">
  {{ .Inner | markdownify }}
</div>

Markdown 中使用：

{{< notice type="warning" >}}
这里是一段提示内容。
{{< /notice >}}

摘要控制

Hugo 可以自动生成摘要，也可以手动指定分隔符：

这是文章开头，会出现在摘要中。




这里是正文的后续部分。

Front Matter 中也可以写：

summary: "这是一段手写摘要。"

优先级通常是手写 summary 高于 <!--more-->，再高于自动摘要。

别名与旧链接跳转

迁移站点时可以使用 aliases 保留旧链接：

---
title: "新的文章地址"
aliases:
  - /old-post/
  - /2024/old-post.html
---

Hugo 会为旧地址生成跳转页面。部署后，旧链接访问者会跳到新页面。

中文内容建议

  • 设置 hasCJKLanguage = true
  • 标题尽量稳定，URL 使用 slug 控制
  • 中文标签不要无限扩散，定期合并同义标签
  • 代码块加语言标识，方便高亮
  • 图片写清楚 alt，利于可访问性和搜索
  • 长文用二级、三级标题组织层级

示例：

```go
fmt.Println("Hello Hugo")
```

内容目录建议

个人博客可以这样组织：

content/
├── posts/          # 正式文章
├── notes/          # 短笔记
├── docs/           # 系列文档
├── photos/         # 相册
├── bookmarks/      # 书签
├── about.md
└── _index.md

技术文档可以这样组织：

content/docs/
├── _index.md
├── getting-started/
│   ├── _index.md
│   ├── installation.md
│   └── quick-start.md
├── guides/
└── reference/

发布前检查

  • 标题、描述、日期是否完整
  • draft 是否已经改为 false
  • 图片路径是否正确
  • 分类和标签是否统一
  • 内链是否能打开
  • 旧文章迁移是否配置 aliases
  • 本地执行 hugo --minify 是否成功

下一步

继续阅读 模板系统，学习内容如何变成最终页面。

评论

0%