Hugo Fundamentals: A Complete Beginner's Guide

September 12, 2025

What is Hugo?

Think of Hugo as a website construction worker. You give it:

Raw materials (your content in Markdown files)
A blueprint (templates)
Instructions (configuration)

And Hugo builds a complete website with HTML, CSS, and JavaScript that can run anywhere.

Key Point: Hugo is a Static Site Generator - it creates regular HTML files, not dynamic websites that need databases or server-side processing.

Core Philosophy: Separation of Concerns

Hugo separates three main things:

CONTENT (What you say)
    ↓
TEMPLATES (How it looks)
    ↓
CONFIGURATION (Site settings)
    ↓
STATIC WEBSITE

This separation means you can change the design without touching content, or change content without breaking the design.

Basic Hugo Site Structure

my-hugo-site/
├── content/           ← Your actual content (blog posts, pages)
├── layouts/           ← Templates that control how content looks
├── static/            ← Images, CSS, JS files (copied as-is)
├── data/              ← Data files (JSON, YAML, CSV)
├── assets/            ← Files that need processing (SCSS, etc.)
├── themes/            ← Downloaded themes
├── public/            ← Generated website (don't edit this!)
├── config.yaml        ← Site configuration
└── hugo.mod           ← If using Hugo Modules

1. Content: Your Writing

Content Files

content/
├── _index.md          ← Homepage content
├── about.md           ← /about/ page
├── blog/
│   ├── _index.md      ← /blog/ page
│   ├── my-first-post.md   ← /blog/my-first-post/
│   └── another-post.md    ← /blog/another-post/
└── docs/
    ├── _index.md      ← /docs/ page
    └── installation.md    ← /docs/installation/

Markdown + Front Matter

Every content file has two parts:

---
title: "My First Blog Post"
date: 2024-01-15
draft: false
tags: ["hugo", "tutorial"]
---

# This is the content

This is written in **Markdown** and becomes the actual page content.

Front Matter (the stuff between ---) = Metadata Content (below the ---) = What visitors read

URL Structure

Hugo automatically creates URLs from your folder structure:

content/about.md → yoursite.com/about/
content/blog/first-post.md → yoursite.com/blog/first-post/

2. Layouts: The Templates

Layouts are like cookie cutters - they define the shape, and your content fills them.

Template Hierarchy

Hugo looks for templates in this order:

1. layouts/blog/single.html     ← Specific to blog posts
2. layouts/_default/single.html ← General template
3. themes/mytheme/layouts/...   ← Theme templates

Common Layout Types

layouts/
├── _default/
│   ├── baseof.html      ← Base template (defines overall structure)
│   ├── single.html      ← Individual pages/posts
│   ├── list.html        ← Lists of content (blog index)
│   └── index.html       ← Homepage
├── partials/
│   ├── header.html      ← Reusable header
│   ├── footer.html      ← Reusable footer
│   └── navigation.html  ← Reusable navigation
└── shortcodes/
    └── youtube.html     ← Custom content snippets

How Templates Work

baseof.html (the master template):

<!DOCTYPE html>
<html>
<head>
    <title>{{ .Title }} - {{ .Site.Title }}</title>
</head>
<body>
    {{ partial "header.html" . }}
    
    <main>
        {{ block "main" . }}{{ end }}
    </main>
    
    {{ partial "footer.html" . }}
</body>
</html>

single.html (for individual posts):

{{ define "main" }}
    <h1>{{ .Title }}</h1>
    <p>Published: {{ .Date.Format "Jan 2, 2006" }}</p>
    {{ .Content }}
{{ end }}

Hugo injects the single.html content into the {{ block "main" . }}{{ end }} section of baseof.html.

3. The Template Language

Hugo uses Go templates with special syntax:

Variables and Data Access

{{ .Title }}           ← Current page title
{{ .Content }}         ← Current page content
{{ .Date }}            ← Current page date
{{ .Site.Title }}      ← Site title from config
{{ .Site.Params.author }} ← Custom param from config

Loops

{{ range .Pages }}
    <h2><a href="{{ .Permalink }}">{{ .Title }}</a></h2>
{{ end }}

Conditionals

{{ if .Params.featured }}
    <p>This is a featured post!</p>
{{ end }}

Partials (Reusable Components)

{{ partial "header.html" . }}

4. Configuration: Site Settings

Your config.yaml controls global settings:

baseURL: "https://mysite.com"
title: "My Awesome Site"
languageCode: "en-us"

params:
  author: "Your Name"
  description: "My personal blog"
  
menu:
  main:
    - name: "Home"
      url: "/"
    - name: "Blog" 
      url: "/blog/"

5. Themes: Pre-built Designs

Themes are complete layout packages. Two ways to use them:

Git Submodules (Traditional)

git submodule add https://github.com/user/theme-name themes/theme-name

Hugo Modules (Modern)

hugo mod init github.com/yourusername/yoursite
hugo mod get github.com/user/theme-name

Then activate in config:

theme: "theme-name"  # For submodules
# OR
module:
  imports:
    - path: "github.com/user/theme-name"  # For modules

6. The Build Process

When you run hugo, this happens:

1. Read config.yaml
2. Scan content/ for Markdown files
3. Process front matter
4. Convert Markdown to HTML
5. Find appropriate templates
6. Inject content into templates
7. Process assets (SCSS, images)
8. Output final HTML to public/

7. Development vs Production

Development

hugo server        # Start development server

Runs on http://localhost:1313
Auto-reloads when you change files
Shows draft content
Fast rebuilds

Production

hugo               # Build for production

Creates optimized files in public/
Excludes drafts
Minifies CSS/JS
Ready to upload to web server

8. Content Organization Strategies

By Type

content/
├── blog/          ← Blog posts
├── docs/          ← Documentation
├── projects/      ← Portfolio items
└── pages/         ← Static pages

By Date

content/
└── posts/
    ├── 2024/
    │   ├── 01/
    │   └── 02/
    └── 2023/

Sections

Each top-level folder in content/ is a section:

content/blog/ = “blog” section
content/docs/ = “docs” section

Sections can have their own templates and behavior.

9. Common Workflows

Creating Content

hugo new blog/my-new-post.md    # Creates content/blog/my-new-post.md

Development Cycle

1. hugo server              # Start development
2. Edit content files
3. See changes instantly
4. hugo                     # Build when ready
5. Deploy public/ folder

Customizing Themes

1. Copy theme template to layouts/
2. Modify the copy
3. Hugo uses your version automatically

10. Key Mental Models

Think of Hugo as a Factory

Raw Materials: Markdown files, images, data
Blueprints: Templates and themes
Assembly Line: Hugo’s build process
Final Product: Static HTML website

Templates are Molds

Content gets poured into template molds
Same mold (template) can create many products (pages)
You can have different molds for different types of content

Configuration is the Control Panel

One place to change site-wide settings
Themes read these settings to customize behavior
Like adjusting factory settings

11. Why Static Sites?

Advantages:

Fast: No database queries, just serving files
Secure: No server-side code to exploit
Scalable: Can handle massive traffic
Simple: Easy to backup, move, and deploy
Version Control: Everything is files you can track

Trade-offs:

No real-time features (comments need external services)
Content updates require rebuilding
Dynamic features need JavaScript/external APIs

Getting Started Mindset

Start Simple: Use a theme, write content, customize gradually
Understand the Flow: Content → Templates → Static Site
Learn by Doing: Don’t try to understand everything at once
Use the Hierarchy: Hugo’s lookup system lets you override anything
Think in Components: Partials let you reuse template pieces

Hugo’s power comes from this separation of concerns - once you understand that content, presentation, and configuration are separate but connected, everything else starts to make sense!

A Guide to Verifying Digital Signatures and Understanding the Chain of Trust