Setup Hugo

Install Hugo

winget install Hugo.Hugo.Extended
hugo version

Install Go

winget install GoLang.Go
go version

Check if git is installed

git --version

Desired folder structure

knowledge/
│
├── book-site/
│   ├── content/docs
│   ├── themes/
│   ├── hugo.toml
│   └── ...
│
├── notes-site/
│   ├── content/docs
│   ├── themes/
│   ├── hugo.toml
│   └── ...
│
├── .github/
│   └── workflows/
│
└── README.md

Create knowledge repository folder

mkdir C:\projects\knowledge
cd C:\projects\knowledge

Create sites

hugo new site book-site
hugo new site notes-site

knowledge/
├── book-site/
└── notes-site/

Initialize Git at the Root

cd knowledge
git init

Add themes

cd knowledge

git submodule add https://github.com/alex-shpak/hugo-book.git book-site/themes/hugo-book

git submodule add https://github.com/adityatelange/hugo-PaperMod.git notes-site/themes/PaperMod

Repository now looks like:

knowledge/
│
├── .gitmodules
│
├── book-site/
│   └── themes/
│       └── hugo-book
│
└── notes-site/
    └── themes/
        └── PaperMod

Create a .gitignore

knowledge/.gitignore

Add the following to the .gitignore

# Hugo build output
book-site/public/
notes-site/public/

# Hugo cache
book-site/resources/
notes-site/resources/

# OS files
.DS_Store
Thumbs.db

# VS Code
.vscode/

Create GitHub Repository

On GitHub:

New Repository

knowledge

Do not initialize it with:

  • README
  • .gitignore
  • License

Locally:

First Commit

cd knowledge

git add .
git commit -m "Initial Hugo book and notes sites"

Connect to GitHub

git remote add origin https://github.com/<username>/knowledge.git

Verify:

git remote -v

Push

git branch -M main

git push -u origin main

Now GitHub contains:

knowledge/
│
├── book-site/
├── notes-site/
├── .gitmodules
├── .github/
└── README.md

Working Day-to-Day

Create a note:

cd notes-site

hugo new personal-finance/retirement_computation.md

Edit the note in VSCode

Commit the change to the git

cd ..

git add .
git commit -m "Added retirement computation note"
git push

GitHub Actions Later

Once this is working, you can add:

.github/
└── workflows/
    ├── deploy-book.yml
    └── deploy-notes.yml

Then every push automatically:

GitHub
   |
Build Hugo
   |
Upload to S3
   |
Invalidate CloudFront

No manual deployment.

Configure a Theme

Book Site

cd knowledge\book-site
hugo mod init github.com/<your-github-id>/book-site

<your-github-id> = alokmodak

Edit hugo.toml:

baseURL = "/"
locale = "en-us"
title = "Alok's Book"

theme = "hugo-book"

[module]
[[module.imports]]
path = "github.com/alex-shpak/hugo-book"

Notes Site

cd ..\notes-site
hugo mod init github.com/<your-github-id>/notes-site

<your-github-id> = alokmodak

Edit hugo.toml:

baseURL = '/'
locale = 'en-us'
title = 'Alok's Notes'

theme = "PaperMod"

[module]
[[module.imports]]
path = "github.com/adityatelange/hugo-PaperMod"

Download Theme Dependencies

For Book Site:

cd knowledge\book-site
hugo mod tidy

For Notes Site:

cd ..\notes-site
hugo mod tidy

Start the Development Server

cd knowledge\notes-site
hugo server

This will likely use:

http://localhost:1313

If the port is already used:

hugo server -p 1314

and then open

http://localhost:1314

Build the Static Site

Book

cd knowledge\book-site
hugo

Output:

book-site/
└── public/

Example:

book-site/public/
├── index.html
├── chapter-01/
└── sitemap.xml

Preview the Generated Site

You can even serve the generated files:

cd public
python -m http.server 8080

Open:

http://localhost:8080

book-site/
└── content/
    └── docs/
        ├── _index.md
        │
        ├── section-1/
        │   ├── _index.md
        │   ├── chapter-01.md
        │   └── chapter-02.md
        │
        ├── section-2/
        │   ├── _index.md
        │   ├── chapter-03.md
        │   └── chapter-04.md
        │
        └── appendix/
            ├── _index.md
            └── references.md

Hugo Command Cheat Sheet

Category Command Purpose
Create Site hugo new site book-site Create a new Hugo site
Create Site hugo new site notes-site Create a new Hugo site
Module hugo mod init github.com/alokmodak/book-site Initialize Hugo module
Module hugo mod init github.com/alokmodak/notes-site Initialize Hugo module
Module hugo mod tidy Download/update module dependencies
Module hugo mod graph Show loaded modules
Module hugo mod clean Clean module cache
Content hugo new aws/fargate.md Create a new content page
Content hugo new hugo/setup-hugo.md Create a page inside a section
Content hugo new docs/chapter-01.md Create a new book chapter
Local Server hugo server Start local development server
Local Server hugo server -D Include draft content
Local Server hugo server -p 1314 Run on a different port
Local Server hugo server --disableFastRender Disable fast rendering (debugging)
Local Server hugo server --disableFastRender --cleanDestinationDir Clean and rebuild site
Build hugo Generate static site into public/
Inspect hugo list all List all pages, sections, and content
Inspect hugo env Show Hugo environment information
Inspect hugo version Show Hugo version
Preview Build python -m http.server 8080 Serve generated public/ folder locally
Git git init Initialize Git repository
Git git add . Stage all changes
Git git commit -m "message" Commit changes
Git git push -u origin main Push to GitHub

Common Hugo Content Structure

Type Path Purpose
Home Page content/_index.md Site landing page
Section Page content/aws/_index.md Section landing page
Section Page content/hugo/_index.md Section landing page
Content Page content/aws/fargate.md Individual note/page
Content Page content/hugo/setup-hugo.md Individual note/page
Book Chapter content/docs/chapter-01.md Book content

Daily Workflow (Notes)

cd notes-site

hugo new aws/route53.md

hugo server

Most Useful Debug Commands

Command When to Use
hugo list all Content not appearing
hugo server --disableFastRender Theme/layout issues
hugo mod tidy Module/theme problems
hugo Verify production build
hugo mod graph Verify loaded themes/modules
hugo env Check Hugo/Go environment

How to Change a Hugo Theme

This guide assumes you are using Hugo Modules.

Step 1: Backup Your Current Site

Before changing anything, commit your current working version.

git add .
git commit -m "Backup before theme change"

Step 2: Stop the Hugo Server

If Hugo is running, stop it.

Ctrl + C

Step 3: Update hugo.toml

Open:

hugo.toml

Remove the old theme configuration and add the new one.

Example: Change to Hugo Book

[module]
[[module.imports]]
path = "github.com/alex-shpak/hugo-book"

Example: Change to Docsy

[module]
[[module.imports]]
path = "github.com/google/docsy"

Example: Change to PaperMod

[module]
[[module.imports]]
path = "github.com/adityatelange/hugo-PaperMod"

Step 4: Download the New Theme

Run:

hugo mod tidy

This downloads the theme and updates dependencies.

Step 5: Verify the Theme Loaded

Run:

hugo mod graph

Example output:

github.com/alokmodak/notes-site github.com/google/docsy

Step 6: Start Hugo

Run:

hugo server

If you encounter issues, use:

hugo server --disableFastRender

Step 7: Check the Site

Open:

http://localhost:1313

Verify:

  • Home page loads
  • Navigation works
  • Pages are visible
  • Images load correctly

Step 8: If Something Looks Wrong

Clean and rebuild:

hugo server --disableFastRender --cleanDestinationDir

If module issues occur:

hugo mod clean
go clean -modcache
hugo mod tidy

Step 9: Verify Content Exists

Run:

hugo list all

Make sure your pages and sections appear.

Example:

content/aws/fargate.md
content/hugo/setup-hugo.md
content/aws/_index.md

Step 10: Build Production Site

Generate static files:

hugo

Output will be created in:

public/

Quick Theme Change Checklist

1. git commit current site
2. Stop Hugo server
3. Update hugo.toml
4. Run: hugo mod tidy
5. Run: hugo mod graph
6. Run: hugo server
7. Verify pages
8. Run: hugo build
9. Commit changes

Useful Commands

Command Purpose
hugo mod tidy Download/update theme
hugo mod graph Show active theme
hugo mod clean Clear Hugo module cache
go clean -modcache Clear Go cache
hugo server Start local server
hugo server --disableFastRender Debug rendering issues
hugo list all Show all content
hugo Build production site
git add . && git commit -m "message" Save working state