CS

Hugo

Reference for the Hugo static site generator: installation, CLI commands, configuration, content structure, theming, deployment, and performance tuning.

What this covers

Hugo is a fast, flexible static site generator built in Go. This page covers installing it, scaffolding and running a site, the CLI commands you’ll reach for day to day, configuration, content structure, theming, deployment, and performance tuning.

When to use it

  • Installing Hugo or scaffolding a brand-new site
  • Running the local dev server, including drafts, custom ports, or alternate configs
  • Creating and organizing content (posts, pages, page bundles)
  • Editing config.toml — menus, output formats, taxonomies, image processing
  • Managing Hugo modules or theme submodules
  • Customizing a theme’s layouts, SCSS, or CSS custom properties
  • Deploying to GitHub Pages, Netlify, or AWS S3 + CloudFront
  • Tuning build performance or diagnosing slow/broken builds
  • Troubleshooting a theme that won’t load or content that won’t show up

Quick Start

Installation

macOS:

brew install hugo

Windows:

winget install Hugo.Hugo.Extended

Linux:

sudo apt install hugo  # Ubuntu/Debian
sudo dnf install hugo  # Fedora

Create a New Site

# Create new site
hugo new site my-website
cd my-website

# Initialize Git repository
git init

# Add a theme (Ananke example)
git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke.git themes/ananke

# Configure theme in config
echo "theme = 'ananke'" >> config.toml

# Create your first post
hugo new posts/my-first-post.md

# Start development server
hugo server -D

Project-specific examples:

hugo new site ceramics-site
hugo new site blog-site
hugo new site portfolio-site

CLI Commands Reference

Development Server

# Start development server
hugo server

# Start server with drafts included
hugo server -D

# Start server on specific port
hugo server --port 8080

# Start server with live reload disabled
hugo server --disableLiveReload

# Start server with specific config
hugo server --config config-dev.toml

# Start server with verbose output
hugo server -v

Content Commands

Create new content:

# Create new post
hugo new posts/my-new-post.md

# Create new page
hugo new about.md

# Create content with specific type
hugo new --kind post posts/tech-article.md

List content:

# List all content
hugo list all

# List drafts
hugo list drafts

# List pages by kind
hugo list pages

Build Commands

# Build site to public directory
hugo

# Build with drafts
hugo -D

# Build to specific directory
hugo -d dist

# Build with minification
hugo --minify

# Build with garbage collection
hugo --gc

# Clean public directory before build
hugo --cleanDestinationDir

Advanced Build Options

Environment-specific builds:

# Build for production
hugo --environment production

# Build with specific config
hugo --config config-prod.toml,config.toml

Performance diagnostics:

# Build with template metrics
hugo --templateMetrics --templateMetricsHints

# Build with step analysis
hugo --stepAnalysis

Module Management

# Initialize modules
hugo mod init github.com/user/my-site

# Get specific module version
hugo mod get github.com/gohugoio/hugo-mod-jslibs-dist/popperjs/v2@v2.211.0

# Update all modules
hugo mod tidy

# Clean module cache
hugo mod clean

Theme Management

# List available themes
hugo list themes

# Update theme submodule
git submodule update --remote themes/theme-name

# Update Hugo module theme
hugo mod get -u github.com/user/theme

Configuration

Basic Configuration (config.toml)

baseURL = "https://example.com"
languageCode = "en-us"
title = "My Hugo Site"
theme = "ananke"

[params]
  description = "A fast and flexible static site generator"
  author = "Hugo Authors"

[menu]
  [[menu.main]]
    name = "Home"
    url = "/"
    weight = 1

  [[menu.main]]
    name = "Posts"
    url = "/posts/"
    weight = 2

Advanced Configuration

Multiple output formats:

[outputs]
  home = ["HTML", "RSS", "JSON"]
  page = ["HTML"]
  section = ["HTML", "RSS"]
  taxonomy = ["HTML", "RSS"]
  taxonomyTerm = ["HTML"]

Image processing:

[imaging]
  quality = 75
  resampleFilter = "Lanczos"
  anchor = "Center"

Taxonomies:

[taxonomies]
  tag = "tags"
  category = "categories"
  author = "authors"

Content & Front Matter

Front Matter

YAML example:

---
title: "My First Post"
date: 2023-12-01T10:00:00Z
draft: false
tags: ["hugo", "static-site"]
categories: ["blog"]
author: "John Doe"
---

# Post Content Here

TOML example:

+++
title = "My First Post"
date = 2023-12-01T10:00:00Z
draft = false
tags = ["hugo", "static-site"]
categories = ["blog"]
author = "John Doe"
+++

# Post Content Here

Content Organization

Directory structure:

content/
├── _index.md          # Homepage content
├── about.md           # About page
├── posts/
│   ├── _index.md      # Posts listing page
│   ├── post1.md       # Individual post
│   └── post2.md
└── projects/
    ├── _index.md      # Projects listing
    └── project1.md

Page Bundles

Leaf bundle:

content/posts/my-post/
├── index.md
├── image1.jpg
└── image2.png

Branch bundle:

content/posts/
├── _index.md
├── post1/
│   └── index.md
└── post2/
    └── index.md

Themes and Customization

Theme Structure

themes/my-theme/
├── layouts/
│   ├── _default/
│   │   ├── baseof.html
│   │   ├── list.html
│   │   └── single.html
│   ├── partials/
│   │   ├── header.html
│   │   └── footer.html
│   └── shortcodes/
├── static/
│   ├── css/
│   ├── js/
│   └── images/
├── assets/
│   └── scss/
└── theme.toml

Custom CSS

// assets/scss/custom.scss

// Override theme variables
$primary-color: #007acc;
$secondary-color: #6c757d;
$font-family-sans-serif: "Roboto", sans-serif;

// Custom styles
.custom-header {
  background: linear-gradient(135deg, $primary-color, $secondary-color);
  color: white;
  padding: 2rem 0;

  h1 {
    font-size: 3rem;
    font-weight: 700;
    margin-bottom: 1rem;
  }

  p {
    font-size: 1.2rem;
    opacity: 0.9;
  }
}

.custom-card {
  border: none;
  box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);
  border-radius: 10px;
  transition: transform 0.3s ease;

  &:hover {
    transform: translateY(-5px);
  }
}

CSS Custom Properties

:root {
  --primary-color: #007acc;
  --secondary-color: #6c757d;
  --font-family: 'Inter', sans-serif;
  --border-radius: 8px;
}

Deployment

GitHub Pages

GitHub Actions workflow:

name: Deploy Hugo site to Pages

on:
  push:
    branches: [ main ]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          submodules: true
          fetch-depth: 0

      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: 'latest'
          extended: true

      - name: Build
        run: hugo --minify

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./public

Netlify

netlify.toml:

[build]
  publish = "public"
  command = "hugo --gc --minify"

[build.environment]
  HUGO_VERSION = "0.111.3"

[[redirects]]
  from = "/api/*"
  to = "/.netlify/functions/:splat"
  status = 200

AWS S3 + CloudFront

GitHub Actions for AWS:

- name: Configure AWS credentials
  uses: aws-actions/configure-aws-credentials@v2
  with:
    aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
    aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
    aws-region: us-east-1

- name: Deploy to S3
  run: |
    aws s3 sync public/ s3://${{ secrets.S3_BUCKET }} --delete    

- name: Invalidate CloudFront
  run: |
    aws cloudfront create-invalidation --distribution-id ${{ secrets.CLOUDFRONT_ID }} --paths "/*"

Performance Optimization

Critical CSS Loading

.above-fold {
  // Critical styles loaded immediately
}

Lazy Loading Non-Critical Styles

@media print {
  @import "print";
}

Build Optimizations

  • Use --minify flag for production builds
  • Enable garbage collection with --gc
  • Use Hugo modules for better dependency management
  • Implement proper caching headers
  • Optimize images with Hugo’s image processing

Best Practices

  1. Content organization: Use consistent front matter and directory structure
  2. Performance: Enable minification and optimize assets
  3. SEO: Configure proper meta tags and structured data
  4. Accessibility: Ensure proper heading hierarchy and alt text
  5. Version control: Use Git submodules for themes
  6. CI/CD: Implement automated deployment pipelines
  7. Security: Keep Hugo and themes updated
  8. Monitoring: Use analytics and performance monitoring

Troubleshooting

Theme not loading:

# Check theme submodule
git submodule status

# Update theme
git submodule update --remote themes/theme-name

Content not showing:

# Check front matter
hugo list drafts

# Build with verbose output
hugo -v

Performance issues:

# Check build metrics
hugo --templateMetrics --templateMetricsHints

# Analyze build steps
hugo --stepAnalysis
← Back to Homepage