Right, let’s talk about archetypes/. This directory is one of those Hugo features that seems almost trivial until you use it correctly, at which point you wonder how you ever lived without it. It’s the antidote to the soul-crushing tedium of manually creating the same front matter for every new blog post, product page, or whatever content type you have.

Think of an archetype as a template for new content. It’s a blueprint. When you run hugo new posts/my-great-post.md, Hugo doesn’t just create a blank file. It looks in archetypes/ for a file named posts.md (or the default default.md) and uses it to pre-populate that new file with front matter. This is how you avoid forgetting to set that draft: true flag for new posts or manually typing out the same taxonomy every single time.

The Default Archetype

If you do nothing else, create an archetypes/default.md file. This is your catch-all template for any content type that doesn’t have its own specific archetype. At its simplest, it just needs to be a valid Markdown file with front matter. Here’s a boring but functional one:

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

Wait, what’s with the curly braces? That’s Hugo’s templating engine, and it’s the secret sauce. When you run hugo new something.md, Hugo injects variables into this template:

  • {{ .Name }} becomes the filename you chose (my-great-post).
  • {{ .Date }} becomes the current timestamp.

The replace function takes the kebab-case filename and turns it into a Title Case, human-readable string. It’s a small touch that makes your life easier. Now, when you create a new file, it’s pre-populated with a sensible title and, crucially, marked as a draft so you don’t accidentally publish a half-written thought.

Content-Type-Specific Archetypes

The real power comes when you create archetypes for specific content types. Let’s say you have a section for “projects” in your site. Every project page needs specific front matter: a client name, a project URL, a technologies list, and a featured image. Manually adding this is a recipe for inconsistency and forgetfulness.

You solve this by creating archetypes/projects.md. Now, when you run hugo new projects/cool-app.md, it uses this template instead of the default.

---
title: "{{ replace .Name "-" " " | title }}"
date: {{ .Date }}
draft: true
client: "Client Name Inc."
project_url: "https://example.com"
technologies: []
# Pro-tip: Put all your project images in /assets/projects/
# so this path is consistent.
featured_image: "projects/{{ .Name }}/cover.jpg"
# This is a common pitfall: remember the weight for sorting!
weight: 0
---

## Project Overview

Tell me all about this brilliant thing you built.

## The Challenge

What was the problem we were solving?

## The Solution

How did we absolutely nail it?

See? Now you’ve not only standardized your front matter but also given yourself a writing template in the body. This is how you enforce consistency without being a nag. The comment about the image path is the kind of “in-the-trenches” knowledge that saves someone (probably you, future-you is always so forgetful) from a headache later.

The Quirks and The “Why”

You’ll notice the front matter in an archetype uses YAML by default. This is a Hugo convention, and it’s what you should stick with. The archetype file itself is just a template that outputs a valid Markdown file. The final file can be .md, .mmark, or whatever, but the archetype is always .md.

A common “gotcha” is that Hugo merges the archetype with any directory-specific archetypes you might have set up in your content folder. It’s a lookup chain: Hugo first looks for archetypes/[section].md, then archetypes/default.md. This is generally sensible, but just be aware of it if you have a complex structure.

Why go through all this trouble? Because it automates the boring stuff. It reduces human error. It means every new post in your blog has draft: true by default, preventing accidental early publication. It means every project has the same structured data, which makes your templates infinitely easier to write and more reliable. You’re not just building a site; you’re building a sensible, repeatable process for yourself. And that, frankly, is what separates a hobbyist from a professional. Even a professional who makes jokes about YAML indentation.