Hugo Setup and Deploy

Hugo Setup and Deploy

March 20, 2025
Web
Hugo, Deploy, Github

🚀 Hugo + GitHub Pages Setup (User Site) #

Minimal setup using hugo-book theme inside a Conda environment, with GitHub Pages deployment.

1. Create and Activate Conda Environment # 

conda create -n hugo-env
conda activate hugo-env

2. Install Hugo & Create Hugo Site with hugo-book Theme # 

# Install Hugo
sudo apt install hugo         # Or: brew install hugo

# Create Hugo site
hugo new site hugo-site
cd hugo-site

# Initialize git and add theme
git init
git submodule add https://github.com/alex-shpak/hugo-book themes/hugo-book

3. Configure config.toml # 

baseURL = 'https://your-username.github.io/'
languageCode = 'en-us'
title = 'My Hugo Site'
theme = 'hugo-book'

[params]
  BookTheme = 'light'
  BookToC = true
  BookCollapseSection = true
  BookFlatSection = false

[[menu.sidebar]]
  name = "Knowledge Graph"
  url = "/kg/"
  weight = 1

4. Create Content and _index.md Files # 

# Create directories and content
mkdir -p content/kg/topic1
touch content/_index.md
touch content/kg/_index.md
touch content/kg/topic1/_index.md
hugo new kg/topic1/intro.md

Directory Structure # 

content/
├── _index.md
├── kg/
│   ├── _index.md
│   └── topic1/
│       ├── _index.md
│       └── intro.md

_index.md contents #

content/_index.md

---
title: "Home"
---

content/kg/_index.md

---
title: "Knowledge Graph"
bookFlatSection: false
bookCollapseSection: true
---

content/kg/topic1/_index.md

---
title: "Topic 1"
---

5. Create GitHub Repository #

  • Create repo: your-username.github.io
    (Required for GitHub User Pages)

6. GitHub Deployment #

a. Generate a Personal Access Token (PAT) #

b. Initial Deployment (One-Time) # 

hugo
cd public
git init
git checkout -b main
git remote add origin https://github.com/your-username/your-username.github.io.git
git add .
git commit -m "Initial deploy"
git push -u origin main
cd ..

c. Create Auto Deploy Script #

deploy.sh

#!/bin/bash
hugo -D && cd public && git add . && git commit -m "Updated site" && git push origin main && cd ..
echo "✅ Deployment Complete!"

Make executable:

chmod +x deploy.sh

Run anytime:

./deploy.sh

7. Check Deployment #

  • GitHub → Repository → Settings → Pages
    • Source: main
    • Folder: / (root)
  • Live Site: https://your-username.github.io/

8. Notes #

  • _index.md files define sections and sidebar headings
  • bookFlatSection = false preserves folder hierarchy
  • bookCollapseSection = true enables collapsible sidebar
  • hugo -D includes drafts when building