Hugo Content Conventions

#

Frontmatter and page-bundle rules for every Markdown file under content/.

Required Fields

#

Every blog post in content/blog/ must include:

---
title: "Post Title"
date: "YYYY-MM-DD"
slug: "lowercase-hyphenated-slug"
description: "SEO description, 140-156 characters"
tags: ["lowercase", "tag", "values"]
---

Field Rules

#

Optional Fields

#

• series: ["Series Name"] — for multi-part posts.
• draft: true — hides from production build (visible with hugo server -D).

Page Bundle Structure

#

Each blog post is a page bundle — a folder containing index.md and all related assets. Folder names use the format YYYY-MM-DD_slug/:

content/blog/2026/2026-01-03_the-four-repo-gitops-structure-for-my-homelab-platform/
  index.md          # Post content with frontmatter
  featured.png      # Thumbnail/hero image (auto-detected by Blowfish)
  diagram.png       # Any other images used in the post

• Place a featured.png (or .jpg) for the thumbnail/hero; Blowfish detects it automatically.
• Store all images for a post (screenshots, diagrams, etc.) inside the same folder.
• Reference images in Markdown with relative paths: ![alt](diagram.png).

Anti-Patterns

#

• Do not use featureimage, featured_image, cover, or image frontmatter keys — place a featured.png in the page bundle folder instead.
• Do not store post images outside the page bundle folder — keep all images co-located with index.md.
• Do not use absolute URLs in aliases — use path-only format: ["/old-slug/"].
• Do not add trailing slashes to slug values.
• Do not create posts as standalone .md files — always use the page bundle folder structure YYYY-MM-DD_slug/index.md.