Hugo Static Site Generator

Quick Reference

• Docs: https://gohugo.io/documentation/
• Forum: https://discourse.gohugo.io/
• GitHub: https://github.com/gohugoio/hugo
• Template functions: https://gohugo.io/functions/
• Configuration: https://gohugo.io/configuration/introduction/

Core Commands

hugo new site my-site        # Create new site
hugo new theme my-theme      # Create theme skeleton
hugo new content posts/my-post.md  # Create content
hugo server -D               # Dev server (include drafts)
hugo server --navigateToChanged    # Auto-navigate to changed content
hugo                         # Build site to public/
hugo --minify                # Build with minified output
hugo --gc                    # Build and clean unused cache
hugo mod init github.com/user/repo  # Initialize Hugo modules

Project Structure

my-site/
├── hugo.toml              # Site configuration
├── archetypes/            # Content templates for `hugo new`
│   └── default.md
├── assets/                # Files processed by Hugo Pipes (Sass, JS, images)
├── content/               # Site content (Markdown)
├── data/                  # Data files (JSON, TOML, YAML)
├── i18n/                  # Translation strings
├── layouts/               # Templates (override theme)
├── static/                # Static files copied as-is
├── themes/                # Installed themes
└── public/                # Generated site (build output)

Workflow

Creating a New Site

1. Run

   hugo new site <name>

   to scaffold
2. Configure

   hugo.toml

   — see references/configuration.md
3. Add a theme (install or create custom) — see references/theme-development.md
4. Create content with

   hugo new content <section>/<name>.md

5. Run

   hugo server -D

   for live development
6. Build with

   hugo --minify

   for production

Theme Development

• Theme directory structure and skeleton
• Template lookup order
• Base templates (

  baseof.html

  ) and blocks
• Partials and partial caching
• List and single templates
• Taxonomy and term templates

Templating

• Go template syntax and functions
• Context (the dot

  .

  ) and variable scoping
• Range, with, if/else patterns
• Custom shortcodes
• Template debugging

Content Management

• Page bundles (leaf vs branch)
• Front matter fields
• Sections and taxonomies
• Menus
• Multilingual / i18n
• Content archetypes

Asset Pipeline

• Image processing (resize, crop, filters, WebP)
• Sass/SCSS compilation
• JavaScript bundling with esbuild
• Fingerprinting and SRI
• PostCSS / Tailwind CSS integration

Deployment

• Netlify configuration
• Vercel setup
• Cloudflare Pages
• GitHub Pages with Actions
• General CI/CD patterns

Best Practices

• Keep images with content: Use page bundles (

  index.md

  + images in same directory) so Hugo can process them
• Use

  hugo.toml

  config directory for complex sites: split into

  config/_default/hugo.toml

  ,

  menus.toml

  ,

  params.toml

• Asset pipeline minimum: Always

  minify

  ,

  fingerprint

  , and use

  slice

  for CSS/JS bundles
• Override, don't fork themes: Place overriding templates in project

  layouts/

  — Hugo's union file system gives project files precedence over theme files
• Use partials for DRY templates: Break complex templates into focused partials; use

  partialCached

  for expensive operations
• Content organization mirrors URL structure: Top-level directories under

  content/

  become sections
• Draft workflow: Use

  draft: true

  in front matter;

  hugo server -D

  shows drafts, production build excludes them
• Use archetypes: Define content templates in

  archetypes/

  for consistent front matter across content types