Home on HCD

Understanding Hugo

Sat, 15 Aug 2026 04:09:57 +0800

Hugo is a static site generator (SSG) written in Go. Because it builds static sites, you don't need to worry about server overhead or maintenance. Hugo has many strengths. Speed is just one of them. Flexible configuration, scalability, extensibility, and out-of-the-box readiness are among its other advantages.

Installing Hugo and Its Toolchain

Sat, 15 Aug 2026 04:09:57 +0800

This page explains how to install Hugo on each operating system and set up the environment variable (PATH) it needs to run.

Hugo Editions

Hugo ships in three editions.

Introduction

Mon, 01 Jan 0001 00:00:00 +0000

This section is a reference, listing every Hugo built-in tool.

Introduction

Mon, 01 Jan 0001 00:00:00 +0000

This article assumes you already have a basic understanding of programming languages, so it won't introduce programming concepts from scratch. Instead, it builds on that foundation to introduce Hugo's syntax.

Project Structure and UFS

Mon, 01 Jan 0001 00:00:00 +0000

Project Structure

A standard Hugo project has this structure:

my-project/
├── archetypes/ # Default templates for new content
├── assets/ # Can be processed via Hugo Pipes (CSS, JS, images)
├── static/ # Can't be processed, copied to output as is
├── config/
│ ├── _default/ # Default config
│ │ └── hugo.yaml # Site configuration, can also live in the project root
│ └── production/ # Environment-specific overrides
├── content/ # Markdown content 
├── data/ # Custom data files (JSON/YAML/yaml) for templates
├── i18n/ # Translations
├── layouts/ # Template files, the site's HTML structure
├── public/ # Build output directory
├── resources/ # Resource processing cache
└── themes/ # Theme (if installed via git submodule)

resources and public are regenerated on every build. You should add both directories to .gitignore, since there's no benefit to tracking generated files in Git.

Basic Syntax

Mon, 01 Jan 0001 00:00:00 +0000

Arithmetic and Comparison

Hugo doesn't support symbols like + or <. You need to use function calls for these operations.

{{ add 1 1 }}
{{ sub 2 1 }}
{{ mul 2 2 }}
{{ div 4 2 }}
{{ eq 1 1 }}
{{ ne 1 2 }}
{{ lt 1 2 }}
{{ le 2 2 }}
{{ gt 3 2 }}
{{ ge 2 2 }}

2
1
4
2
true
true
true
true
true
true

if / else if / else

The basic if-else syntax. false, an empty string, 0, nil, an empty slice, and an empty dict are all falsy values.

Content Management

Mon, 01 Jan 0001 00:00:00 +0000

This article covers everything related to the content directory.

Creating a Site

Mon, 01 Jan 0001 00:00:00 +0000

This page explains how to create a new site with Hugo and start the local development server.

Create a Project

hugo new project my-site --format yaml
cd my-site

hugo new project creates the basic directory structure. At this point, the site has no theme or content yet.

Content Authoring

Mon, 01 Jan 0001 00:00:00 +0000

This page covers the Markdown, front matter, and shortcode syntax you'll use when writing content.

Content Structure

A content directory looks like this:

content
├── _index.md # 1. Home page
├── docs
│ ├── _index.md # 2. List page
│ ├── p1.md # 3-1. Post page: filename only
│ ├── p2 # 3-2. Post page: using index.md
│ │ ├── foo.jpg
│ │ └── index.md
│ └── bar # Nested list
│ ├── _index.md # List page for the nested section
│ ├── post-1.md
│ └── post-2.md
└── tags
 ├── _index.md # 4. List page for tags
 └── my-tag.md # Tag page

The home page is the _index.md at the top level
Every other _index.md with a leading underscore is a list page
A post page can use either a filename.md or a filename/index.md, cannot have child pages
A tag's _index.md is likewise a list page

Both p1.md and p2/index.md can create a standalone post, but only the latter can hold its own page resources, such as images or videos. You should default to the post-name/index.md form to keep your project structure consistent, except in two cases:

Resource Processing

Mon, 01 Jan 0001 00:00:00 +0000

resource.Resource objects handle Hugo's resource processing.

Creation

You can create resource.Resource objects in several ways. As global functions, you have:

These four methods are used to retrieve resources from the assets directory. To retrieve resources from the current page, use .Resources.Get, .Resources.GetMatch, and so on instead.

Development Setup

Mon, 01 Jan 0001 00:00:00 +0000

This article covers development-related setup for working with Hugo.

Editor Setup

VS Code syntax highlighting and autocomplete: theNewDynamic/language-hugo-vscode
JetBrains syntax highlighting and autocomplete: Smart Hugo

Formatter Setup

HTML

You can use a Prettier plugin to format HTML + Go template files.

Multilingual Sites

Mon, 01 Jan 0001 00:00:00 +0000

In Hugo, each language is an independent site In a multilingual website, each language is a site on the language dimension. This page explains how to configure it.

Configuration

Declare the languages your site uses in hugo.yaml:

Basic Configuration

Mon, 01 Jan 0001 00:00:00 +0000

Hugo's configuration file has hundreds of possible settings, which is bound to overwhelm beginners. This page's purpose is to highlight the settings in hugo.yaml that matter most, so you don't get lost in the sheer volume of options.

Sites Matrix

Mon, 01 Jan 0001 00:00:00 +0000

Each language is its own independent site in Hugo. Hugo v0.153.0 went further and introduced the sites matrix concept, raising the old single dimension model of "one language equals one site" into a combination of three dimensions. This page explains the concept and how to use it to control the scope of content generation.

Hugo Modules

Mon, 01 Jan 0001 00:00:00 +0000

This page covers Hugo Modules and the corresponding hugo mod command in detail.

What Is a Module

A module is Hugo's basic unit for organizing content. A module can be a full Hugo project, or it can be a small reusable package that provides just one type of component (content, layouts, assets, data, i18n, static, archetypes). A theme you install is, at its core, a module.

Template System

Mon, 01 Jan 0001 00:00:00 +0000

This article introduces Hugo's template lookup mechanism, which determines which template applies to each page. Three core concepts drive this mechanism: page kind, page type, and the layout manually specified in front matter. Once you understand these core concepts, we'll walk through the full template classification, then explain the complete lookup order. Two examples at the end will tie everything together.

URLs and Routing

Mon, 01 Jan 0001 00:00:00 +0000

This page explains how Hugo determines the URL for each page. Get URL management right from the start. Broken links damage a site more than almost anything else, so plan your approach early.

Data

Mon, 01 Jan 0001 00:00:00 +0000

The Data directory stores only three file types: yaml, YAML, and JSON. What makes this directory distinctive is that once Hugo starts, its contents get loaded into Hugo's memory and stay there until the build finishes, without ever being cleared in between. Large structural files that aren't shared across multiple pages should go in the assets directory instead, since Hugo garbage-collects the memory assets files occupy once processing completes.

Deploying Your Site

Mon, 01 Jan 0001 00:00:00 +0000

To deploy your site to the public internet, Hugo's official documentation provides an extensive walkthrough. See the official documentation.

If you're a beginner without a clear idea of where to start, hugo-community-docs recommend the GitHub Pages option, since it lets you complete everything on a single platform.

Configuration Index

Mon, 01 Jan 0001 00:00:00 +0000

See the official Hugo documentation's configuration index page.

Content Adapter

Mon, 01 Jan 0001 00:00:00 +0000

Content adapters are used to build dynamic pages, most commonly for generating API documentation. A pre-build script creates a structured JSON file, and the content adapter reads that data file to automatically generate pages. For usage details, see the official documentation.

API Index

Mon, 01 Jan 0001 00:00:00 +0000

You can think of Hugo development as its own language. It wraps Go's functionality for use in templates, and parses templates and reflects variables on its own, so it has effectively become a language in its own right. Only a limited subset of Go's functionality is exposed, so even if you're already familiar with Go and Go templates, you'll still need to check the documentation to use Hugo correctly.

Build a Theme

Mon, 01 Jan 0001 00:00:00 +0000

This article walks you through building a theme from scratch. Learning by doing gets you there faster.

Create the Project

hugo new project my-blog --format=yaml
cd my-blog

Stylesheet

Get the styles ready first. CSS has nothing to do with templates, so copy a simple template into assets/css/main.css for now.

Output Formats

Mon, 01 Jan 0001 00:00:00 +0000

Hugo supports having a single page produce multiple output formats. This is configured through output formats.

Output formats commonly serve three purposes:

Generating a site-wide JSON index for search.
Using build order to preprocess data before rendering.
Outputting Markdown (for example, llms.txt) for AI tools or other consumers to read.

Basic Configuration

Define the format you want to output in hugo.yaml:

CLI Index

Mon, 01 Jan 0001 00:00:00 +0000

The index below is compiled from the official Hugo documentation. This site doesn't duplicate that content. Follow the links back to the official pages to look things up.

hugo config mounts

hugo import jekyll

hugo server trust

hugo version

FAQ

Mon, 01 Jan 0001 00:00:00 +0000

Link Checking

You can integrate external tools to verify link correctness. For example, rumdl's MD057 rule supports Markdown links and assets, along with absolute link detection and completion.