Hugo Reference
Hugo is the world's fastest static site generator. It builds sites in milliseconds and supports advanced content management features.
Installation
Windows
# Using Chocolatey
choco install hugo-extended
# Using Scoop
scoop install hugo-extended
# Using Winget
winget install Hugo.Hugo.Extended
macOS
# Using Homebrew
brew install hugo
Linux
# Debian/Ubuntu (snap)
snap install hugo --channel=extended
# Using package manager (may not be latest)
sudo apt-get install hugo
# Or download from https://gohugo.io/installation/
Quick Start
Create New Site
# Create site
hugo new site mysite
cd mysite
# Initialize git and add theme
git init
git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke themes/ananke
echo "theme = 'ananke'" >> hugo.toml
# Create first post
hugo new content posts/my-first-post.md
# Start development server
hugo server -D
Directory Structure
mysite/
├── archetypes/ # Content templates
│ └── default.md
├── assets/ # Assets to process (SCSS, JS)
├── content/ # Markdown content
│ └── posts/
├── data/ # Data files (YAML, JSON, TOML)
├── i18n/ # Internationalization
├── layouts/ # Templates
│ ├── _default/
│ ├── partials/
│ └── shortcodes/
├── static/ # Static files (copied as-is)
├── themes/ # Themes
└── hugo.toml # Configuration
CLI Commands
| Command | Description |
|---|---|
hugo new site <name> |
Create new site |
hugo new content <path> |
Create content file |
hugo |
Build to public/ |
hugo server |
Start dev server |
hugo mod init |
Initialize Hugo Modules |
hugo mod tidy |
Clean up modules |
Build Options
# Basic build
hugo
# Build with minification
hugo --minify
# Build with drafts
hugo -D
# Build for specific environment
hugo --environment production
# Build to custom directory
hugo -d ./dist
# Verbose output
hugo -v
Server Options
# Start with drafts
hugo server -D
# Bind to all interfaces
hugo server --bind 0.0.0.0
# Custom port
hugo server --port 8080
# Disable live reload
hugo server --disableLiveReload
# Navigate to changed content
hugo server --navigateToChanged
Configuration (hugo.toml)
# Basic settings
baseURL = 'https://example.com/'
languageCode = 'en-us'
title = 'My Hugo Site'
theme = 'ananke'
# Build settings
[build]
writeStats = true
# Markdown configuration
[markup]
[markup.goldmark]
[markup.goldmark.extensions]
definitionList = true
footnote = true
linkify = true
strikethrough = true
table = true
taskList = true
[markup.goldmark.parser]
autoHeadingID = true
autoHeadingIDType = 'github'
[markup.goldmark.renderer]
unsafe = false
[markup.highlight]
style = 'monokai'
lineNos = true
# Taxonomies
[taxonomies]
category = 'categories'
tag = 'tags'
author = 'authors'
# Menus
[menus]
[[menus.main]]
name = 'Home'
pageRef = '/'
weight = 10
[[menus.main]]
name = 'Posts'
pageRef = '/posts'
weight = 20
# Parameters
[params]
description = 'My awesome site'
author = 'John Doe'
Front Matter
Hugo supports TOML, YAML, and JSON front matter:
TOML (default)
+++
title = 'My First Post'
date = 2025-01-28T12:00:00-05:00
draft = false
tags = ['hugo', 'tutorial']
categories = ['blog']
author = 'John Doe'
+++
Content here...
YAML
---
title: "My First Post"
date: 2025-01-28T12:00:00-05:00
draft: false
tags: ["hugo", "tutorial"]
---
Content here...
Templates
Base Template (_default/baseof.html)
<!DOCTYPE html>
<html>
<head>
<title>{{ .Title }} | {{ .Site.Title }}</title>
{{ partial "head.html" . }}
</head>
<body>
{{ partial "header.html" . }}
<main>
{{ block "main" . }}{{ end }}
</main>
{{ partial "footer.html" . }}
</body>
</html>
Single Page (_default/single.html)
{{ define "main" }}
<article>
<h1>{{ .Title }}</h1>
<time>{{ .Date.Format "January 2, 2006" }}</time>
{{ .Content }}
</article>
{{ end }}
List Page (_default/list.html)
{{ define "main" }}
<h1>{{ .Title }}</h1>
{{ range .Pages }}
<article>
<h2><a href="{{ .Permalink }}">{{ .Title }}</a></h2>
<p>{{ .Summary }}</p>
</article>
{{ end }}
{{ end }}
Shortcodes
Built-in Shortcodes
{{< figure src="/images/photo.jpg" title="My Photo" >}}
{{< youtube dQw4w9WgXcQ >}}
{{< gist user 12345 >}}
{{< highlight go >}}
fmt.Println("Hello")
{{< /highlight >}}
Custom Shortcode (layouts/shortcodes/alert.html)
<div class="alert alert-{{ .Get "type" | default "info" }}">
{{ .Inner | markdownify }}
</div>
Usage:
{{< alert type="warning" >}}
**Warning:** This is important!
{{< /alert >}}
Content Organization
Page Bundles
content/
├── posts/
│ └── my-post/ # Page bundle
│ ├── index.md # Content
│ └── image.jpg # Resources
└── _index.md # Section page
Accessing Resources
{{ $image := .Resources.GetMatch "image.jpg" }}
{{ with $image }}
<img src="{{ .RelPermalink }}" alt="...">
{{ end }}
Hugo Pipes (Asset Processing)
SCSS Compilation
{{ $styles := resources.Get "scss/main.scss" | toCSS | minify }}
<link rel="stylesheet" href="{{ $styles.RelPermalink }}">
JavaScript Bundling
{{ $js := resources.Get "js/main.js" | js.Build | minify }}
<script src="{{ $js.RelPermalink }}"></script>
Taxonomies
Configure
[taxonomies]
tag = 'tags'
category = 'categories'
Use in Front Matter
+++
tags = ['go', 'hugo']
categories = ['tutorials']
+++
List Taxonomy Terms
{{ range .Site.Taxonomies.tags }}
<a href="{{ .Page.Permalink }}">{{ .Page.Title }} ({{ .Count }})</a>
{{ end }}
Multilingual Sites
defaultContentLanguage = 'en'
[languages]
[languages.en]
title = 'My Site'
weight = 1
[languages.es]
title = 'Mi Sitio'
weight = 2
Troubleshooting
| Issue | Solution |
|---|---|
| Page not found | Check baseURL configuration |
| Theme not loading | Verify theme path in config |
| Raw HTML not showing | Set unsafe = true in goldmark config |
| Slow builds | Use --templateMetrics to debug |
| Module errors | Run hugo mod tidy |
| CSS not updating | Clear browser cache or use fingerprinting |