How to Make Hugo Pages — Complete Guide with All Commands

Hugo is one of the fastest static site generators available. This site itself is built with Hugo and the PaperMod theme, deployed to GitHub Pages. This guide covers everything from installation to publishing.

Install Hugo
Create a New Site
Add a Theme
Configure Your Site
Create Pages and Posts
Front Matter Reference
Build and Preview
Deploy to GitHub Pages
Useful Hugo Commands

1. Install Hugo

Hugo Extended is required for SCSS processing (used by most themes).

Arch Linux

sudo pacman -S hugo

Debian / Ubuntu

sudo apt install hugo
# Or install extended version from GitHub releases:
HUGO_VERSION=0.147.9
wget https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.deb
sudo dpkg -i hugo_extended_${HUGO_VERSION}_linux-amd64.deb

macOS

brew install hugo

Verify

hugo version
# Should show "extended" in the output

2. Create a New Site

# Create site directory
hugo new site my-blog
cd my-blog

# Initialize git
git init

Your directory structure:

my-blog/
├── archetypes/       # Content templates
├── assets/           # SCSS, JS (processed by Hugo)
├── content/          # Your pages and posts (Markdown)
├── data/             # Data files (YAML/JSON/TOML)
├── layouts/          # Custom layout overrides
├── static/           # Static files (images, favicon)
├── themes/           # Themes
└── hugo.toml         # Site configuration

3. Add a Theme

Option A: Git submodule (recommended)

git submodule add https://github.com/adityatelange/hugo-PaperMod.git themes/hugo-PaperMod
echo 'theme = "hugo-PaperMod"' >> hugo.toml

Option B: Clone directly

git clone https://github.com/adityatelange/hugo-PaperMod.git themes/hugo-PaperMod

4. Configure Your Site

Edit hugo.toml:

baseURL = "https://aayrix.github.io/"
languageCode = "en-us"
title = "Aayrix"
theme = "hugo-PaperMod"

[pagination]
pagerSize = 5

[params]
defaultTheme = "dark"
ShowReadingTime = true
ShowShareButtons = true
ShowCodeCopyButtons = true
author = "Aayrix"

[params.homeInfoParams]
Title = "Welcome to Aayrix"
Content = "Tutorials on Linux, GitHub, Hugo, and developer tooling."

[[params.socialIcons]]
name = "github"
url = "https://github.com/aayrix"

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

5. Create Pages and Posts

Create a blog post

hugo new posts/my-first-post.md

This creates content/posts/my-first-post.md with default front matter.

Create a regular page

hugo new about.md        # → content/about.md  →  /about/
hugo new contact.md      # → content/contact.md  →  /contact/
hugo new projects/_index.md  # → section index page

Create a section

# Create a "guides" section
mkdir -p content/guides
hugo new guides/linux-basics.md

Manual file creation

You can also create Markdown files directly:

mkdir -p content/posts
nano content/posts/hello-world.md

Example content:

+++
date = '2026-06-04T10:00:00+05:00'
title = 'Hello World'
description = 'My first Hugo post'
tags = ['hugo', 'blog']
categories = ['Tutorials']
+++

Hello! This is my first post built with Hugo.

6. Front Matter Reference

Hugo supports TOML (+++), YAML (---), or JSON front matter.

Field	Description	Example
`title`	Page title	`"My Post"`
`date`	Publish date	`'2026-06-04T10:00:00+05:00'`
`draft`	Hide from production	`true`
`description`	SEO summary	`"A short description"`
`tags`	Tag list	`['hugo', 'web']`
`categories`	Category list	`['Tutorials']`
`ShowToc`	Show table of contents	`true`
`weight`	Sort order (lower = first)	`1`

Draft posts

# Create as draft (default)
hugo new posts/draft-post.md

# Publish — set draft = false in front matter, or:
hugo new content/posts/draft-post.md

7. Build and Preview

Local development server

# Start dev server with live reload
hugo server -D

# Open in browser
# http://localhost:1313

Build for production

# Build site (excludes drafts)
hugo

# Build including drafts
hugo -D

# Build with minification
hugo --minify

# Output goes to public/
ls public/

Clean build cache

hugo --gc --minify

8. Deploy to GitHub Pages

Step 1: Create GitHub repository

gh repo create aayrix.github.io --public --source=. --remote=origin

Step 2: Add GitHub Actions workflow

Create .github/workflows/hugo.yaml:

mkdir -p .github/workflows

name: Deploy Hugo site to Pages

on:
  push:
    branches: [master]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  build:
    runs-on: ubuntu-latest
    env:
      HUGO_VERSION: 0.147.9
    steps:
      - uses: actions/checkout@v4
        with:
          submodules: recursive
          fetch-depth: 0
      - name: Install Hugo
        run: |
          wget -O /tmp/hugo.deb https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.deb
          sudo dpkg -i /tmp/hugo.deb
      - uses: actions/configure-pages@v5
        id: pages
      - name: Build
        run: hugo --gc --minify --baseURL "${{ steps.pages.outputs.base_url }}/"
      - uses: actions/upload-pages-artifact@v3
        with:
          path: ./public

  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
    steps:
      - uses: actions/deploy-pages@v4

Step 3: Enable GitHub Pages

# Via GitHub CLI
gh api repos/aayrix/aayrix.github.io/pages -X POST -f build_type=workflow

# Or in browser: Settings → Pages → Source: GitHub Actions

Step 4: Push and deploy

git add .
git commit -m "Initial Hugo site"
git push -u origin master

Your site will be live at https://aayrix.github.io/ within a few minutes.

9. Useful Hugo Commands

# Create new content
hugo new posts/article-name.md

# Start dev server
hugo server -D

# Build production site
hugo --minify

# List all content
hugo list all

# Check for broken links (with hugo-mod plugin)
hugo --printPathWarnings

# Show site structure
hugo config mounts

# Get help
hugo help
hugo help new

Quick workflow summary

# Daily writing workflow
hugo new posts/new-article.md   # 1. Create post
hugo server -D                  # 2. Preview locally
# Edit content/posts/new-article.md
hugo --minify                   # 3. Build
git add . && git commit -m "Add new article" && git push  # 4. Deploy

This Site as Reference

This blog is a working example of everything above:

Source: github.com/aayrix/my-blog (update with your actual repo URL)
Live site: aayrix.github.io
Theme: hugo-PaperMod

For GitHub setup and authentication, see the GitHub Install & Usage Guide.

Table of Contents#

1. Install Hugo#

Arch Linux#

Debian / Ubuntu#

macOS#

Verify#

2. Create a New Site#

3. Add a Theme#

Option A: Git submodule (recommended)#

Option B: Clone directly#

4. Configure Your Site#

5. Create Pages and Posts#

Create a blog post#

Create a regular page#

Create a section#

Manual file creation#

6. Front Matter Reference#

Draft posts#

7. Build and Preview#

Local development server#

Build for production#

Clean build cache#

8. Deploy to GitHub Pages#

Step 1: Create GitHub repository#

Step 2: Add GitHub Actions workflow#

Step 3: Enable GitHub Pages#

Step 4: Push and deploy#

9. Useful Hugo Commands#

Quick workflow summary#

This Site as Reference#

Table of Contents