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:

Here is a typical Hugo project layout

Extending a Hugo Theme Without Overwriting It

Extending means modifying only specific parts of a theme while keeping the rest intact. Instead of fully overriding a file, you inject your changes where the theme allows.

1. How Hugo Extends Themes

Hugo uses blocks, partials, and hooks to allow customization without replacing entire files.

• Blocks (baseof.html) – Let you modify content inside a theme’s base layout.
• Partials (partials/*.html) – Let you modify specific sections (e.g., header, footer).
• Hooks (custom-defined blocks) – Some themes define specific “hook” areas for injecting content.

2. Using Blocks to Extend Theme Layouts

Many Hugo themes use baseof.html as a master template.
Inside this file, they define blocks, which child layouts (like single.html, list.html) can modify.

How Hugo Works: Full Breakdown

Hugo follows a structured process to convert Markdown files into a fully functional static website. Here’s how it does it, step by step:

1. Configuration: Reading config.toml, config.yaml, or config.json

What Happens?

When you run hugo server or hugo to build the site, Hugo first loads the configuration file from the root of your project.

What Does Hugo Look For?

• Site-wide settings:
  • baseURL = "https://example.com" → Defines the website’s base URL
  • languageCode = "en-us" → Sets the default language
  • title = "My Website" → The default site title
• Theme settings:
  • theme = "mytheme" → Defines which theme to use
• Permalinks:
  • permalinks = { blog = "/blog/:slug/" } → Custom URL structures
• Menus & navigation:
  • menu = { main = [{ name = "About", url = "/about/" }] }
• Output formats:
  • outputs = { home = ["HTML", "RSS"], section = ["HTML"], page = ["HTML"] }
• Content directories:
  • contentDir = "content" → Sets where Hugo looks for content
  • layoutsDir = "layouts" → Sets where Hugo looks for layouts

How Hugo Processes This?

• Loads the config file from root
• Reads settings and stores them in memory
• Applies default settings for any missing values

2. Content Processing (content/ directory & front matter)

What Happens?

Hugo scans the content/ directory for Markdown (.md) files.

Hugo’s File Loading Order: Project vs. Theme

Hugo follows a priority system when reading files:

1. Project-level files (your custom files)
   • If a file exists in your project (layouts/partials/header.html), Hugo uses that first.
2. Theme-level files
   • If the file isn’t in your project, Hugo looks in the theme (themes/mytheme/layouts/partials/header.html).
3. Hugo defaults
   • If no file exists in either place, Hugo may use a built-in default (rare but possible).

This means:

• If you copy header.html into layouts/partials/, Hugo will use that version instead of the theme’s.
• If you don’t copy header.html, it will fall back to the theme’s version.
• If the theme doesn’t have a header.html, Hugo just won’t include one.

Front Matter & Archetypes

Using archetypes is better than manually adding front matter to every .md file.

Hugo is a fast, static site generator that follows a structured process to build your website.

Here’s how it works:

1. Configuration (config.toml, config.yaml, config.json)

Hugo first reads the configuration file from the root of your project (config.toml, config.yaml, or config.json). This file sets global settings like:

• Base URL (baseURL)
• Theme (theme)
• Menus (menu)
• Permalinks (permalinks)
• Language settings (defaultContentLanguage)

2. Content Processing (content/ directory & front matter)

Each Markdown file (.md) in the content/ folder is treated as a page. Hugo reads the front matter (YAML, TOML, or JSON at the top of the file), which contains metadata like:

Keeping Theme Customisations While Using Git Submodules or Cloning

If you use a Git submodule or clone a theme, any changes made directly in the theme directory will be lost when you set up a new machine. To avoid this, all modifications should go in your project root.

Best Workflow for Customising a Theme Without Losing Changes

1. Keep the theme as a Git submodule (or clone it).
2. Place all modifications in your project root (without modifying the theme directly).
3. Ensure your repository includes only your customizations (not the theme itself).
4. Set up your project on a new machine properly to restore both your files and the theme.

Step 1: Clone a Theme as a Submodule (Recommended)

Instead of cloning the theme manually, add it as a Git submodule:

Definition of Extending in Hugo

Extending a theme means modifying or adding to its functionality without replacing entire files. You do this by:

1. Using blocks ({{ block "name" . }}) inside baseof.html or other templates.
2. Overriding specific parts of a theme by placing modified versions in your project.
3. Using Hugo’s lookup order, which prefers your custom files over theme files.

Key Point: Hugo will ignore the theme’s file if you fully override it. But if the theme supports blocks, you can extend it without fully replacing it.