Skip to main content
Front matter is metadata that appears at the top of your content files. It provides Hugo with information about your content, such as the title, date, and publication status.

​
Front matter format

Hugo supports multiple front matter formats. The benson.vc site uses TOML format, which is enclosed in +++ markers: 
+++
title = 'Your Post Title'
date = 2026-03-03T10:00:00-08:00
draft = false
+++

Your content goes here...

​
Alternative formats

Hugo also supports YAML (enclosed in ---) and JSON formats, but TOML is recommended for consistency with the existing site.

​
Required fields

These fields should be included in every post:

​
title

The title of your post, displayed as the page heading and in listings: 
title = 'On the Proliferation of Artificial Intelligence'
  • Use title case or sentence case consistently
  • Wrap the value in single quotes
  • Special characters and apostrophes are supported

​
date

The publication date and time for your post: 
date = 2018-07-28T18:02:45-08:00
  • Use RFC 3339 format: YYYY-MM-DDTHH:MM:SS-TZ:TZ
  • Include timezone information (e.g., -08:00 for PST)
  • Hugo uses this for sorting posts chronologically
  • The date appears in post listings and on the post page

​
draft

Controls whether the post is published or hidden: 
draft = false
  • draft = false - Post is published and visible in production
  • draft = true - Post is hidden unless running with -D flag
  • Use drafts while writing and reviewing content

​
Optional fields

​
robots

Control search engine indexing for the post: 
robots = 'noindex, nofollow'
Common values:
  • 'index, follow' - Allow indexing and following links (default)
  • 'noindex, nofollow' - Prevent indexing and following links
  • 'noindex, follow' - Prevent indexing but allow following links
  • 'index, nofollow' - Allow indexing but prevent following links
Use this to exclude posts from search engine results.

​
description

A brief summary of the post for SEO and social sharing: 
description = 'An exploration of the benefits and risks of artificial intelligence proliferation'
  • Keep it concise (150-160 characters)
  • Used in meta tags and social media previews
  • Improves SEO and click-through rates

​
tags

Categorize your post with tags: 
tags = ['artificial intelligence', 'technology', 'policy']
  • Use an array of strings
  • Tags can be used for filtering and organization
  • Congo theme can display tags on post pages

​
categories

Group posts into broader categories: 
categories = ['Essays', 'Technology']
  • Use an array of strings
  • Typically broader than tags
  • Creates category taxonomy pages

​
author

Specify the post author: 
author = 'John Doe'
  • Can be a string or reference to author data
  • Congo theme can display author information

​
slug

Customize the URL slug for the post: 
slug = 'custom-url-slug'
  • Overrides the default slug generated from the directory name
  • Use lowercase and hyphens
  • Useful for shorter or more readable URLs

​
aliases

Create redirect aliases for the post: 
aliases = ['/old-url/', '/another-old-url/']
  • Maintains old URLs when restructuring content
  • Hugo creates redirect pages automatically
  • Preserves SEO value and prevents broken links

​
Real example

Here’s the complete front matter from a real post on the benson.vc site: 
+++
title = 'On the Proliferation of Artificial Intelligence'
date = 2018-07-28T18:02:45-08:00
draft = false
+++
This minimal example includes only the required fields. The post is published, titled, and timestamped.

​
Extended example

Here’s what a more comprehensive front matter configuration might look like: 
+++
title = 'Understanding Modern AI Development'
date = 2026-03-03T14:30:00-08:00
draft = false
description = 'A comprehensive guide to modern AI development practices and emerging trends in machine learning'
author = 'Jane Smith'
tags = ['artificial intelligence', 'machine learning', 'development']
categories = ['Technology', 'Guides']
slug = 'modern-ai-development'
robots = 'index, follow'
+++

​
Date formatting

1
Get the current date
2
Use the date command to get the current timestamp:
3
date +%Y-%m-%dT%H:%M:%S%z
4
This outputs: 2026-03-03T14:30:00-0800
5
Format for Hugo
6
Hugo expects the timezone with a colon:
7
date = 2026-03-03T14:30:00-08:00
8
Add the colon between the hour and minute offset.
9
Use in front matter
10
Copy the formatted date into your front matter:
11
+++
title = 'Your Post Title'
date = 2026-03-03T14:30:00-08:00
draft = false
+++

​
Common questions

Hugo will use the file creation date or last modification date as a fallback. However, it’s best practice to always include an explicit date field for consistency and control over post ordering.
Yes, each post can have its own timezone. Hugo will handle timezone conversions and sort posts correctly based on absolute time. This is useful if you’re publishing from different locations or want to schedule posts for specific timezones.
Set the date field to a future date and time. By default, Hugo won’t publish posts with future dates unless you run hugo with the --buildFuture flag. This allows you to prepare content in advance.
The draft field is a boolean that marks content as unpublished. The publishDate field (not shown in the examples) lets you specify when a post should become visible. Use draft = true for work-in-progress content and publishDate for scheduled publishing.
Yes! You can add any custom fields you want. They won’t affect Hugo’s core functionality, but you can access them in your templates. This is useful for theme-specific features or custom data.

​
Best practices

  • Always include title, date, and draft fields
  • Use consistent date formatting across all posts
  • Add description for better SEO
  • Use draft = true while writing, set to false when ready to publish
  • Keep titles concise and descriptive
  • Use tags and categories for better content organization
  • Test locally before publishing to verify front matter is correct

​
Validation

Verify your front matter is valid by running: 
hugo server -D
If there are syntax errors in your front matter, Hugo will display error messages indicating the file and line number with the problem.

​
Resources

Build docs developers (and LLMs) love

Get started for freeTalk to us