内容管理基础

Hugo 的内容管理被描绘为一个高度灵活、以文件为中心且功能强大的体系,旨在让用户能够以多种方式组织、创建、丰富和处理其网站内容。Hugo 的核心优势——速度和灵活性——在内容管理方面得到了充分体现。

内容组织与结构

基于目录的组织方式

Hugo 采用以目录为基础的组织方式,项目的目录结构直接反映渲染后网站的结构。

项目目录结构

使用 hugo new site 命令生成的标准项目结构:

my-site/
├── archetypes/     # 内容模板
├── assets/         # 资源文件(需要处理的)
├── content/        # 内容源文件
├── data/          # 数据文件
├── layouts/       # 布局模板
├── static/        # 静态文件(直接复制)
├── themes/        # 主题
└── hugo.toml      # 配置文件

content 目录结构

content 目录是内容源文件的主要存放地:

content/
├── _index.md              # 网站首页内容
├── about.md               # 关于页面
├── posts/                 # 文章目录
│   ├── _index.md         # 文章列表页
│   ├── first-post.md     # 单个文章
│   └── second-post.md    
├── projects/              # 项目目录
│   ├── _index.md         # 项目列表页
│   └── project-one/      # 页面包
│       ├── index.md      # 项目详情
│       ├── image1.jpg    # 项目资源
│       └── image2.jpg    
└── docs/                 # 文档目录
    ├── _index.md         # 文档首页
    ├── getting-started.md
    └── advanced/
        ├── _index.md
        └── configuration.md

特殊文件说明

_index.md 文件

这些特殊文件用于为不同类型的列表页面添加前置元数据和内容:

  • 首页 (home)content/_index.md
  • 章节页 (section)content/posts/_index.md
  • 分类页 (taxonomy):自动生成或自定义
  • 术语页 (term):自动生成或自定义

页面捆绑 (Page Bundles)

Hugo v0.32 引入了页面捆绑,允许将页面相关的资源打包在一起:

content/
└── posts/
    └── my-post/           # 页面捆绑目录
        ├── index.md       # 页面内容
        ├── featured.jpg   # 特色图片
        ├── diagram.svg    # 图表
        └── data.json      # 相关数据

页面资源可通过 Page.Resources 方法访问:

{{ range .Resources.ByType "image" }}
    <img src="{{ .Permalink }}" alt="{{ .Title }}">
{{ end }}

联合文件系统

Hugo 创建虚拟的联合文件系统,允许将多个目录挂载到相同的目标位置:

  • 项目根目录文件享有最高优先级
  • 其次是主题文件
  • 支持从其他 Hugo 项目或共享内容挂载

内容格式与渲染

支持的内容格式

原生支持格式

  • Markdown:默认格式,使用 Goldmark 引擎
  • HTML:直接 HTML 内容
  • Emacs Org Mode:Emacs 用户友好格式

外部渲染器格式

需要安装外部渲染器:

  • AsciiDoc:需要 AsciiDoctor
  • Pandoc:需要 Pandoc
  • reStructuredText:需要 rst2html

Markdown 渲染详解

Goldmark 引擎特性

Hugo 使用 Goldmark 引擎,符合 CommonMark 和 GitHub Flavored Markdown 规范:

# 标题

## 支持的扩展

- CJK 支持(中日韩文字)
- 定义列表
- 脚注[^1]
- ~~删除线~~
- 表格
- 任务列表
- 排版功能

[^1]: 这是脚注内容

## 定义列表示例

苹果
: 一种水果

橙子
: 另一种水果

## 表格示例

| 功能 | 支持 | 备注 |
|------|------|------|
| 基本 Markdown | ✅ | 完全支持 |
| 扩展语法 | ✅ | 部分支持 |

## 任务列表

- [x] 已完成任务
- [ ] 未完成任务

代码高亮配置

# hugo.toml
[markup]
  [markup.highlight]
    style = 'github'
    lineNos = true
    lineNumbersInTable = false
    noClasses = false

数学公式与图表

数学公式支持

通过 Goldmark 的 Passthrough 扩展支持 LaTeX 语法:

行内公式:$E = mc^2$

块级公式:
$$\sum_{i=1}^{n} x_i = x_1 + x_2 + \cdots + x_n$$

图表支持

  • GoAT ASCII 图表:原生支持
  • Mermaid 图表:通过自定义渲染钩子
<!-- GoAT 示例 -->
```text
    .----.
   /      \
  |  GoAT  |
   \      /
    '----'
Mermaid Diagram
Mermaid Diagram

前置元数据 (Front Matter)

基本概念

前置元数据位于每个内容文件的顶部,以结构化的方式提供页面信息:

---
title: "文章标题"
date: 2025-06-19T10:00:00+08:00
draft: false
description: "文章描述。"
tags: ["标签 1", "标签 2"]
categories: ["分类 1"]
author: "作者名"
---

这里是文章正文内容...

支持格式

YAML 格式(推荐)

---
title: "YAML 格式示例"
date: 2025-06-19
tags: ["hugo", "yaml"]
params:
  author: "John Doe"
  featured: true
---

TOML 格式

+++
title = "TOML 格式示例"
date = 2025-06-19
tags = ["hugo", "toml"]

[params]
author = "John Doe"
featured = true
+++

JSON 格式

{
  "title": "JSON 格式示例",
  "date": "2025-06-19",
  "tags": ["hugo", "json"],
  "params": {
    "author": "John Doe",
    "featured": true
  }
}

常用字段说明

基础字段

---
title: "页面标题"              # 页面标题
date: 2025-06-19T10:00:00+08:00  # 发布日期
lastmod: 2025-06-20T15:30:00+08:00  # 最后修改日期
publishDate: 2025-06-19T08:00:00+08:00  # 发布时间
expiryDate: 2025-12-31T23:59:59+08:00   # 过期时间
draft: false                   # 草稿状态
description: "页面描述。"        # 页面描述
summary: "页面摘要"           # 页面摘要
weight: 10                    # 排序权重
---

URL 控制字段

---
slug: "custom-slug"           # 自定义 URL 片段
url: "/custom/path/"          # 完整自定义 URL
aliases:                      # URL 别名(重定向)
  - "/old-url/"
  - "/another-old-url/"
---

分类字段

---
categories: ["技术", "教程"]
tags: ["Hugo", "静态网站", "教程"]
series: ["Hugo 学习系列"]
---

自定义参数

---
params:
  author: "作者名"
  featured: true
  toc: true
  math: true
  diagram: true
  highlight: true
  license: "CC BY-SA 4.0"
---

特殊字段详解

发布控制

---
# 草稿状态 - 不会在生产环境发布
draft: true

# 未来发布 - 只有到达指定时间才发布
publishDate: 2025-07-01T00:00:00+08:00

# 过期时间 - 过期后不再显示
expiryDate: 2025-12-31T23:59:59+08:00
---

可以通过命令行标志覆盖:

hugo --buildDrafts      # 构建草稿
hugo --buildFuture      # 构建未来内容
hugo --buildExpired     # 构建过期内容

无头模式

---
headless: true  # 设置为无头模式
---

无头页面不会单独渲染,但可作为其他页面的资源使用。

内容生成与自动化

原型 (Archetypes)

默认原型

创建 archetypes/default.md

---
title: "{{ replace .Name "-" " " | title }}"
date: {{ .Date }}
draft: true
tags: []
categories: []
---

内容类型原型

创建 archetypes/posts.md

---
title: "{{ replace .Name "-" " " | title }}"
date: {{ .Date }}
draft: true
tags: []
categories: []
author: ""
description: ""
featured_image: ""
---

## 概述

## 详细内容

## 总结

使用原型创建内容

# 使用默认原型
hugo new content/about.md

# 使用特定原型
hugo new posts/my-new-post.md

# 创建页面包
hugo new posts/my-bundle-post/index.md

动态原型

原型支持 Go 模板语法:

---
title: "{{ replace .Name "-" " " | title }}"
date: {{ .Date }}
draft: true
slug: "{{ .Name }}"
categories: ["{{ .File.ContentDir | path.Base | title }}"]
tags: []
author: "{{ .Site.Params.author | default "Admin" }}"
---

# {{ .Name | title }}

发布于 {{ .Date.Format "2006 年 01 月 02 日" }}。





## 内容开始

在这里编写你的内容...

最佳实践

1. 内容组织策略

content/
├── _index.md              # 网站首页
├── about/                 # 关于页面
│   └── index.md
├── blog/                  # 博客
│   ├── _index.md
│   ├── 2025/
│   │   ├── 01/
│   │   └── 02/
│   └── tags/
├── docs/                  # 文档
│   ├── _index.md
│   ├── getting-started/
│   └── advanced/
└── projects/              # 项目展示
    ├── _index.md
    └── project-name/
        ├── index.md
        └── assets/

2. 前置元数据标准化

建立一致的前置元数据规范:

---
# 基础信息
title: ""
date: ""
lastmod: ""
draft: false

# SEO 相关
description: ""
keywords: []

# 分类标签
categories: []
tags: []

# 作者信息  
author: ""

# 页面配置
toc: true
math: false
diagram: false

# 自定义参数
params:
  feature_image: ""
  reading_time: true
---

3. 内容工作流

  1. 规划内容结构 - 设计清晰的目录层次
  2. 创建原型模板 - 标准化内容创建过程
  3. 使用版本控制 - 跟踪内容变更历史
  4. 定期内容审查 - 更新过时内容,移除无效链接

通过合理的内容管理策略,您可以构建结构清晰、易于维护的 Hugo 网站。

文章导航

章节内容

这是章节的内容页面。

章节概览