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.

What Does Hugo Look For?#

Each .md file contains front matter, which controls metadata for that page. Example:

---
title: "My First Post"
date: 2025-01-30
draft: false
categories: ["Hugo"]
tags: ["static site", "markdown"]
---

Hugo extracts this metadata to:

  • Generate proper titles
  • Organize pages into categories
  • Determine if the post should be included (draft: false)

Types of Content Pages#

  • Regular pages (content/blog/my-post.md) → Becomes /blog/my-post/
  • Section pages (content/blog/_index.md) → Defines /blog/ page
  • Homepage (content/_index.md) → Controls the homepage

How Hugo Processes This?#

  • Scans the content/ directory
  • Reads front matter for metadata
  • Parses Markdown into HTML
  • Assigns a layout for each file

3. Templates & Layouts (layouts/ directory)#

What Happens?#

Hugo determines which layout to use for each page.

Layout Lookup Order#

  1. Page-specific layout → layouts/blog/single.html
  2. Section layout → layouts/blog/list.html
  3. Default single post layout → layouts/_default/single.html
  4. Default list layout → layouts/_default/list.html
  5. Base template (baseof.html) → Used if a template extends from it

Template Types#

  • single.html → For individual pages
  • list.html → For section pages
  • _default/baseof.html → Base layout used by other templates
  • partials/ → Reusable components (e.g., header.html, footer.html)

How Hugo Processes This?#

  • Finds the correct layout for each page
  • Renders the page using the chosen template
  • Uses Go Templates to replace variables like {{ .Title }}

4. Static Assets (static/ & assets/ directories)#

What Happens?#

Hugo handles assets like images, CSS, and JavaScript.

Folders Used#

  • static/ → Directly copied to public/ (e.g., static/img/logo.png → /img/logo.png)
  • assets/ → Used for Hugo Pipes (SCSS processing, image minification, etc.)

Example: Hugo Pipes#

If you have assets/css/main.scss, you can process it in a layout:

<link rel="stylesheet" href="{{ $styles := resources.Get "css/main.scss" | toCSS | minify | fingerprint }}" />

How Hugo Processes This?#

  • Copies files from static/ to public/
  • Processes assets/ files using Hugo Pipes
  • Optimizes images and minifies CSS/JS if needed

5. Building the Final Site (public/ directory)#

What Happens?#

Hugo generates the final static site in the public/ directory.

What Does Hugo Do?#

  • Reads all content
  • Applies layouts
  • Generates HTML files
  • Copies static assets
  • Creates pagination & taxonomies

How Hugo Processes This?#

  1. Reads the config file
  2. Scans the content directory
  3. Determines the correct layout
  4. Processes Markdown into HTML
  5. Resolves CSS/JS assets
  6. Writes the final site into public/