技术教程

Hugo Front Matter 完整指南

详细介绍Hugo博客文章Front Matter的所有可用参数及其用法

什么是 Front Matter？

Front Matter 是 Markdown 文件开头的一段元数据，用 --- 包围，采用 YAML 格式。它定义了文章的各种属性，如标题、日期、分类等。

基础必需参数

title

文章标题，必需参数。

title: "文章标题"

date

发布日期，必需参数。格式推荐使用 ISO 8601 标准。

date: 2025-01-16T21:00:00+08:00

日期格式说明：

  • 2025-01-16：简短格式
  • 2025-01-16T21:00:00+08:00：完整格式（推荐，包含时间）
  • 2025-01-16T21:00:00Z：UTC时间

draft

是否为草稿，必需参数。

draft: false  # false=发布，true=草稿

注意：草稿文章在 hugo server 需要加 -D 参数才能预览：

hugo server -D

常用可选参数

description

文章描述/摘要，显示在文章列表页和SEO中。

description: "这是一篇关于Hugo的详细介绍"

使用建议：

  • 长度：50-150个字符
  • 包含文章关键词
  • 简洁明了地概括文章内容

weight

文章权重，用于控制文章在列表中的排序。权重越大，排序越靠前。

weight: 10

使用场景：

  • 置顶重要文章
  • 自定义文章顺序
  • 配合分类/标签使用

slug

URL路径中的文章标识。如果不设置，Hugo会根据标题自动生成。

slug: "my-custom-url"

示例：

  • 不设置slug：https://example.com/post/hello-world/
  • 设置slug：https://example.com/post/my-custom-url/

url

完整的URL路径，可以完全自定义文章URL。

url: "/2025/01/16/my-article.html"

注意：设置url后会覆盖slug和其他URL设置。

分类和标签

categories

文章分类，层级结构（可以有子分类）。

categories:
    - 技术
    - 编程

或使用数组格式：

categories:
    - 技术
    - 编程

层级示例：

categories:
    - 技术/前端
    - 技术/后端

tags

文章标签，扁平结构（无层级）。

tags:
    - JavaScript
    - Vue
    - 教程

分类vs标签：

  • 分类：层级结构，用于广泛的主题分类
  • 标签：扁平结构，用于具体的主题标记

一篇文章可以有多个分类和多个标签。

作者信息

author

文章作者。

author: "张三"

或使用对象格式：

author:
    name: "张三"
    email: "zhangsan@example.com"
    url: "https://example.com"

authors

多个作者（数组格式）。

authors:
    - name: "张三"
      email: "zhangsan@example.com"
    - name: "李四"
      email: "lisi@example.com"

时间相关参数

publishDate

首次发布日期。如果不设置，使用date参数。

publishDate: 2025-01-16T21:00:00+08:00

expiryDate

内容过期日期。过期后文章不会显示在列表中。

expiryDate: 2026-01-16T21:00:00+08:00

lastmod

最后修改日期。用于SEO和读者参考。

lastmod: 2025-01-16T22:00:00+08:00

自动获取： 如果设置 enableGitInfo = true，Hugo会自动从Git获取最后修改时间。

内容管理

type

内容类型，决定使用哪个模板渲染。

type: "post"

常见类型：

  • post：文章
  • page：独立页面
  • 自定义类型

layout

指定使用的布局模板。

layout: "blog"

使用场景：

  • 覆盖默认模板选择
  • 使用自定义布局

isCJKLanguage

是否为中日韩文字内容。

isCJKLanguage: true

作用：影响摘要生成和字数统计。

输出控制

outputs

输出格式配置。

outputs:
    - HTML
    - JSON
    - RSS

常见组合：

# 仅HTML
outputs:
    - HTML

# HTML + JSON（用于搜索）
outputs:
    - HTML
    - JSON

aliases

URL别名，用于旧URL重定向。

aliases:
    - "/old-url/"
    - "/2020/old-post.html"

使用场景：

  • 文章URL变更
  • 从其他博客迁移
  • 多个URL指向同一文章

SEO相关

keywords

SEO关键词。

keywords:
    - Hugo
    - 静态网站生成器
    - 博客

meta_description

独立的meta描述。

meta_description: "Hugo是一个快速的静态网站生成器"

images

社交分享图片。

images:
    - /images/og-image.jpg

用途：

  • Facebook分享
  • Twitter卡片
  • SEO优化

其他参数

toc

是否显示目录。

toc: true  # true=显示，false=不显示

math

是否启用数学公式。

math: true

comments

是否显示评论。

comments: true  # true=显示，false=不显示

hidden

是否隐藏文章（不在列表中显示，但可通过直接访问URL查看）。

hidden: true

自定义参数

你可以在Front Matter中添加任何自定义参数，在模板中使用。

定义自定义参数

---
title: "我的文章"
date: 2025-01-16
customField: "自定义值"
rating: 5
featured: true
---

在模板中使用自定义参数

{{ .Params.customField }}
{{ .Params.rating }}
{{ .Params.featured }}

完整示例

---
title: "Hugo Front Matter 完整示例"
subtitle: "这是一篇详细介绍Front Matter的文章"  # 副标题
date: 2025-01-16T21:00:00+08:00
lastmod: 2025-01-16T22:30:00+08:00
publishDate: 2025-01-16T21:00:00+08:00
expiryDate: 2026-12-31T23:59:59+08:00
draft: false
description: "这是一篇详细介绍Hugo Front Matter所有参数的文章"
summary: "这是手动指定的摘要"  # 如果设置，优先级高于自动摘要

# 作者信息
author: "张三"
# 或
authors:
    - name: "张三"
      email: "zhangsan@example.com"

# 分类和标签
categories:
    - 技术
    - 教程
tags:
    - Hugo
    - 静态网站
    - 博客

# URL设置
slug: "hugo-frontmatter-example"
url: "/tutorials/hugo/frontmatter/"
aliases:
    - "/old-hugo-post/"
    - "/2020/hugo-guide/"

# 输出控制
type: "post"
layout: "single"
outputs:
    - HTML
    - JSON

# SEO
keywords:
    - Hugo
    - Front Matter
    - 静态网站
meta_description: "学习Hugo Front Matter的所有参数"
images:
    - /images/hugo-og.jpg

# 功能开关
toc: true
math: false
comments: true
isCJKLanguage: true

# 其他
weight: 10
hidden: false
featured: true  # 自定义参数
readingTime: 10  # 自定义参数：阅读时间（分钟）
---

文章正文开始...

Stack主题特有参数

如果你使用的Hugo主题是Stack，还有一些特殊参数：

featuredImage

文章特色图片。

featuredImage: "/images/featured.jpg"

featuredImagePreview

首页预览图片。

featuredImagePreview: "/images/preview.jpg"

hiddenFromHomePage

是否在首页隐藏。

hiddenFromHomePage: false

hiddenFromSearch

是否从搜索中隐藏。

hiddenFromSearch: false

tocOpen

是否默认展开目录。

tocOpen: false

singleColumn

是否使用单列布局。

singleColumn: false

最佳实践

  1. 必需参数：始终设置 title, date, draft
  2. SEO优化：填写 description 和 keywords
  3. 分类标签：合理使用categories和tags
  4. 日期规范：使用 ISO 8601 格式
  5. 自定义参数：根据需要添加，但保持简洁
  6. 一致性：保持所有文章的Front Matter格式一致

常见问题

Q: 如何设置文章摘要？

有三种方式：

  1. 设置 description 参数
  2. 设置 summary 参数
  3. 在文章中使用 `

` 分隔符

Q: 为什么草稿文章看不到？

草稿需要使用 hugo server -D 启动才能预览，或者设置 draft: false。

Q: 如何置顶文章？

设置较大的 weight 值：

weight: 100

Q: 日期格式有要求吗？

推荐使用 ISO 8601 格式：2025-01-16T21:00:00+08:00

Q: 如何禁用某篇文章的评论？

comments: false

总结

Front Matter 是Hugo文章配置的核心，合理使用可以让你的博客更加灵活和强大。建议：

  • 保存一个完整的Front Matter模板
  • 根据实际需求选择使用哪些参数
  • 保持整个博客的配置一致性

相关文章：

© 2026 QichangX
首页