Alright, let’s talk about the default.md archetype. This isn’t just an archetype; it’s the default archetype. It’s the one Hugo uses when it can’t find a more specific template for your content. Think of it as the trusty, slightly battered toolbox you grab for every job when you don’t need the specialized laser-calibrated screwdriver from the blog-post archetype.

Its primary job is to set the baseline, the absolute minimum front matter you should have for a piece of content. And front matter, in case you’re new here, is the metadata block at the top of your content files (YAML, TOML, JSON) that tells Hugo everything it needs to know about your page before it even starts rendering the content itself.

The Bare-Bones Blueprint

Run hugo new posts/my-first-post.md and crack open the generated file. You’ll see something beautifully, almost starkly, simple:

---
title: "My First Post"
date: 2023-10-27T14:23:45-04:00
draft: true
---

That’s it. No frills. title, date, and draft. This is the archetype’s way of saying, “Look, I don’t know what kind of magnificent nonsense you’re about to write, but you’ll probably need these three things.” And it’s right. The title is obvious. The date is crucial for sorting, archiving, and generally knowing what the hell you were thinking about at a given point in time. draft: true is Hugo’s way of gently suggesting you might not be ready to show this to the world yet, which is a feature I’ve come to appreciate more than I’d like to admit.

Why This Minimalism is a Feature, Not a Bug

You might look at this and think, “That’s all? I need tags, categories, a description, an image!” And you’re right, you probably do. But the default.md archetype isn’t supposed to be psychic. Its genius is in its lack of opinion. It’s the foundation upon which you build your more specific, opinionated archetypes.

If every new content file started with 20 pre-populated fields, you’d spend half your time deleting the ones you didn’t need. This approach is the Unix philosophy applied to content creation: do one thing (provide a sensible default) and do it well. The rest is up to you and your more specific archetypes.

Leveling Up: Customizing the Default

The real power move isn’t complaining about the simplicity; it’s customizing it. You don’t like the default fields? Change them! The default.md archetype is just a file in your archetypes directory. No archetypes directory? Make one. No default.md file inside it? Create it. Hugo will use yours instead of its built-in one.

Let’s say your site always uses a featured_image and a description for SEO purposes. Your custom archetypes/default.md would look like this:

---
title: "{{ replace .File.ContentBaseName "-" " " | title }}"
date: {{ .Date }}
draft: true
description: ""
featured_image: "/images/default.jpg"
---

See what we did there? We used Hugo’s text template functions to automatically generate a title from the filename. If you create content/posts/my-awesome-post.md, the title field will be pre-populated with “My Awesome Post”. The {{ .Date }} variable automatically inserts the current datetime. This is where you stop being a user of the system and start being a master of it. You’re encoding your own best practices directly into the content creation process.

The Gotcha: The Content Type Heirarchy

Here’s the part that trips people up. Hugo doesn’t just blindly use default.md every time. It follows a specific lookup order. Let’s say you run hugo new posts/my-post.md.

  1. It first looks for archetypes/posts.md (matching the directory).
  2. If that doesn’t exist, it looks for archetypes/default.md.
  3. If that doesn’t exist, it falls back to its own built-in default.

This means if you have a posts/ section and you find yourself constantly overriding the fields in default.md, you should just create a archetypes/posts.md file. That becomes the template for all new content in the posts directory, leaving your default.md for everything else. It’s a hierarchy of specificity, and understanding it will save you a lot of head-scratching.