Archetypes in Hugo#

Archetypes are templates for new content. When you create a new post with:

hugo new blog/my-post.md

Hugo looks for an archetype to determine the front matter structure.

1. Where Are Archetypes Stored?#

  • Global default: archetypes/default.md
  • Section-specific: archetypes/blog.md (for content/blog/)

2. Example of an Archetype (archetypes/blog.md)#

---
title: "{{ replace .Name "-" " " | title }}"
date: {{ .Date }}
draft: true
author: "Your Name"
tags: []
---

When you run hugo new blog/my-post.md, it creates:

---
title: "My Post"
date: 2025-01-30T12:00:00Z
draft: true
author: "Your Name"
tags: []
---

You can customize this to auto-add categories, descriptions, etc.

Understanding baseof.html in Hugo#

Think of baseof.html as the master layout that wraps every page.

1. Where is baseof.html?#

It’s inside layouts/_default/:

layouts/
└── _default/
    ├── baseof.html
    ├── single.html
    ├── list.html
  • baseof.html → The main template that all layouts extend.
  • single.html → Used for individual pages/posts.
  • list.html → Used for section pages (/blog/, /projects/).

2. How Does baseof.html Work?#

It defines a page structure and uses blocks for dynamic content.

Example baseof.html#
<!DOCTYPE html>
<html lang="en">
<head>
    <title>{{ .Title }}</title>
    <link rel="stylesheet" href="{{ "css/main.css" | relURL }}">
</head>
<body>
    {{ partial "header.html" . }}

    <main>
        {{ block "main" . }}{{ end }}
    </main>

    {{ partial "footer.html" . }}
</body>
</html>

3. How Other Layouts Use It#

Hugo’s other templates (like single.html and list.html) “fill in” baseof.html.

Example single.html (extends baseof.html)#
{{ define "main" }}
<article>
    <h1>{{ .Title }}</h1>
    <p>{{ .Content }}</p>
</article>
{{ end }}
  • {{ define "main" }} replaces the {{ block "main" . }}{{ end }} section in baseof.html.
  • This allows all single pages (/blog/my-post/) to share the same structure.
Example list.html (extends baseof.html)#
{{ define "main" }}
<h1>{{ .Title }}</h1>
<ul>
  {{ range .Pages }}
    <li><a href="{{ .Permalink }}">{{ .Title }}</a></li>
  {{ end }}
</ul>
{{ end }}
  • This is used for listing pages (/blog/, /projects/).

4. Why Use baseof.html?#

  • Avoids duplicating headers/footers in every layout.
  • Keeps layouts clean by defining structure once.
  • Easy customization—change baseof.html, and all pages update.

How to Customize a Theme Without Ejecting#

1. Should You Copy the Whole File?#

No, only copy what you need to modify. Hugo will prioritize files in your project over the theme.

2. What Should You Copy?#

  • If you want to edit a layout, copy the specific file to layouts/:

    cp themes/mytheme/layouts/_default/single.html layouts/_default/single.html
    • Now, layouts/_default/single.html overrides the theme’s version.

  • If you want to edit partials (like headers/footers):

    cp themes/mytheme/layouts/partials/header.html layouts/partials/header.html
    • You can now edit layouts/partials/header.html without changing the theme.

3. Keep the Original?#

Yes, keep the theme in themes/ so you can compare or revert changes.