Hugo Archetypes: Automating Content Frontmatter

Hugo archetypes are content templates that pre-populate frontmatter when you create new content with hugo new. They are a small feature with a disproportionate practical impact on a publication’s day-to-day workflow: every new post or page starts with the correct structure, required fields are present, and authors do not need to remember the exact frontmatter format.

The Default Archetype

Hugo ships with a single default archetype at archetypes/default.md:

---
title: "{{ replace .Name "-" " " | title }}"
date: {{ .Date }}
draft: true
---

When you run hugo new posts/my-new-post.md, Hugo creates the file using this template. The .Name variable is the filename without the extension, and replace .Name "-" " " | title converts my-new-post to My New Post — a reasonable title default.

Customize this default to match your publication’s standard frontmatter:

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

Now every new content file starts with the fields your theme and SEO setup expect.

Section-Specific Archetypes

Archetypes can be scoped to content sections. A file at archetypes/posts.md is used when creating content in the content/posts/ section. A file at archetypes/events.md is used for content/events/.

Hugo’s archetype lookup order:

  1. archetypes/{section}.md
  2. archetypes/default.md
  3. The theme’s archetype if no project-level archetype exists

For a publication with multiple content types, define a specialized archetype for each:

archetypes/posts.md:

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

archetypes/events.md:

---
title: "{{ replace .Name "-" " " | title }}"
date: {{ .Date }}
draft: false
event_date: ""
event_location: ""
event_url: ""
tags: []
---

Brief description of the event.

archetypes/reviews.md:

---
title: "{{ replace .Name "-" " " | title }}"
date: {{ .Date }}
draft: false
rating: 0
product: ""
category: ""
tags: []
featured_image: ""
---

Directory Archetypes (Page Bundles)

For leaf bundle content (posts stored as index.md inside their own directory, alongside their media assets), define the archetype as a directory rather than a single file.

Create archetypes/posts/ as a directory containing index.md:

archetypes/
  posts/
    index.md
    featured.jpg  (optional placeholder)

archetypes/posts/index.md:

---
title: "{{ replace .Name "-" " " | title }}"
date: {{ .Date }}
draft: false
tags: []
featured_image: "featured.jpg"
---

When you run hugo new posts/my-article/, Hugo creates content/posts/my-article/ as a directory and copies the archetype directory contents into it — index.md with the populated frontmatter, and any other files in the archetype directory (placeholder images, associated data files, etc.).

This is the correct pattern for publications where each post has its own media assets stored alongside the content file.

Templating in Archetypes

Archetypes are Go templates with access to a limited set of variables:

  • .Name — the content filename (without extension) or directory name
  • .Date — the current date and time
  • .Type — the content type (section name)
  • .File — the file object with path information

And Hugo’s full template function library, including string manipulation, date formatting, and math functions.

Generate a formatted date in a specific layout:

date: {{ .Date.Format "2006-01-02" }}

Generate a slug from the filename:

slug: "{{ .Name }}"

Produce a specific default category based on the section:

{{ if eq .Type "tutorials" }}
categories: ["Tutorial"]
{{ else }}
categories: []
{{ end }}

Practical Archetype for a Publishing Site

A complete archetype for a publication’s main post type:

archetypes/posts.md:

---
title: "{{ replace .Name "-" " " | title }}"
date: {{ .Date.Format "2006-01-02" }}
draft: false
tags: []
categories: []
featured_image: ""
description: ""
---

Introduction paragraph.

## Section Heading

Content.

The body template below the frontmatter is also inserted into new content files. Including structural scaffolding — an intro paragraph placeholder, a heading — gives writers a starting point without requiring them to remember the publication’s expected structure.

Creating Content with Archetypes

Standard hugo new usage:

# Creates content/posts/my-article.md using archetypes/posts.md
hugo new posts/my-article.md

# Creates content/events/conference-2026/ directory using archetypes/events/ directory
hugo new events/conference-2026/

# Creates with a specific kind, overriding section-based lookup
hugo new --kind reviews products/camera-review.md

The --kind flag forces a specific archetype regardless of the content section, useful for content types that do not map directly to directory names.

Keeping Archetypes Current

Archetypes are templates, not just defaults — they should stay in sync with your actual content requirements. When you add a new frontmatter field that becomes standard across a content type, add it to the archetype. When you retire a field, remove it from the archetype so new content does not start with obsolete frontmatter.

For publications with multiple contributors, clear archetypes reduce the “what frontmatter do I need?” question to zero — the answer is always “whatever hugo new creates.”

Related