Setting Up a Hugo Blog with PaperMod + GitHub + Cloudflare Pages
🚀 Setting Up a Hugo Blog with PaperMod + GitHub + Cloudflare Pages
This guide documents the exact setup used for deploying a Hugo blog with the PaperMod theme to Cloudflare Pages, with version control via GitHub (SSH).
🧱 1. Directory Setup
1
2
mkdir -p ~/projects/faisaldarbar.com
cd ~/projects/faisaldarbar.com
🔧 2. Install Hugo Extended (Linux)
Download and install the extended version of Hugo (required by some themes like PaperMod):
1
2
wget https://github.com/gohugoio/hugo/releases/download/v0.147.9/hugo_extended_0.147.9_linux-amd64.deb
sudo apt install ./hugo_extended_0.147.9_linux-amd64.deb
📂 3. Create a New Hugo Site
Inside the project folder:
1
hugo new site .
This creates the Hugo directory structure in-place.
🎨 4. Add PaperMod Theme (Using Git Submodule ✅)
Add PaperMod theme as a Git submodule:
1
2
git init
git submodule add https://github.com/adityatelange/hugo-PaperMod.git themes/PaperMod
Update hugo.toml:
1
theme = "PaperMod"
📜 5. Create Your First Post
1
hugo new posts/hello-world.md
Edit content/posts/hello-world.md:
1
2
3
4
5
+++
title = 'Hello World'
date = 'YYYY-MM-DDTHH:MM:SS±TZ'
draft = true
+++
🥪 6. Run the Local Server
1
hugo server --buildDrafts
Preview at:
http://localhost:1313
🛠️ 7. Set Up GitHub Repository
✅ Git Configuration
Install Git:
1
sudo apt install git
Configure Git:
1
2
git config --global user.name "Your Name"
git config --global user.email "your@example.com"
🔐 8. Set Up GitHub SSH Access
Generate SSH Key
1
ssh-keygen -t ed25519 -C "your@example.com"
Accept the default path. Then add the public key to GitHub via:
GitHub > Settings > SSH and GPG keys > New SSH Key
Test Connection
1
ssh -T git@github.com
Expected:
“Hi username! You’ve successfully authenticated…”
☁️ 9. Push Site to GitHub
Create a new repo (e.g., faisaldarbar), then:
1
2
3
4
git remote add origin git@github.com:<your-username>/faisaldarbar.git
git add .
git commit -m "Initial Hugo site with PaperMod theme"
git push -u origin main
🌐 10. Deploy to Cloudflare Pages
- Go to Cloudflare Pages
- Click Create Project
- Authorize GitHub and select your repo
- Build settings:
- Framework preset: Hugo
- Build command:
hugo - Output directory:
public
- Deploy 🚀
Live URL:
https://.pages.dev
🔧 11. Fix Links & Base URL
Update hugo.toml:
1
baseURL = "https://<your-site>.pages.dev/"
Commit and push:
1
2
3
git add .
git commit -m "Fix baseURL for Cloudflare Pages"
git push
📋 12. GitHub Actions Taken
- ✅ Created repo (
faisaldarbar) - ✅ Added SSH key to GitHub
- ✅ Authorized GitHub → Cloudflare Pages
- ✅ Configured SSH authentication (avoided storing token)
- ✅ Resolved Git submodule issue by proper theme addition
🧑💻 13. Set Up VS Code on Linux (Optional but Recommended)
Install Visual Studio Code (non-snap method):
1
2
3
4
5
6
7
8
sudo apt update
sudo apt install wget gpg
wget -qO- https://packages.microsoft.com/keys/microsoft.asc | gpg --dearmor > packages.microsoft.gpg
sudo install -o root -g root -m 644 packages.microsoft.gpg /usr/share/keyrings/
sudo sh -c 'echo "deb [arch=amd64 signed-by=/usr/share/keyrings/packages.microsoft.gpg] \
https://packages.microsoft.com/repos/vscode stable main" > /etc/apt/sources.list.d/vscode.list'
sudo apt update
sudo apt install code
📦 Recommended Extensions Install these extensions for better Hugo development:
Hugo Language Support – Syntax highlighting for Hugo templates (ID: budparr.language-hugo-vscode)
Markdown All in One – Enhances Markdown editing (ID: yzhang.markdown-all-in-one)
YAML – Syntax support for .yaml/.toml config files (ID: redhat.vscode-yaml)
GitLens – Advanced Git history and insights (ID: eamodio.gitlens)
🖥️ 14. Multi-Platform Workflow (Linux + Windows)
This project can be managed from both Linux and Windows environments. However, some operations are more stable or predictable in Linux due to Hugo’s tooling and file system differences.
✅ Tasks Safe to Do on Windows (VS Code)
- Writing/editing Markdown posts
- Creating new posts with
hugo new posts/title.md - Running local preview server:
hugo server --buildDrafts - Committing and pushing changes via VS Code
- Previewing site locally
- Updating
hugo.toml, front matter, and minor config changes
Windows Git via VS Code handles basic operations well and securely without requiring manual SSH setup.
⚠️ Tasks Best Done on Linux
| Task | Why Use Linux |
|---|---|
Theme updates (git submodule update) | Git submodules can behave inconsistently on Windows |
Running shell scripts (*.sh) | Native support in Linux |
Advanced Hugo tasks (hugo mod, theme asset builds) | More predictable behavior and compatibility |
| Fixing case-sensitive file issues | Linux file systems are case-sensitive (unlike Windows) |
| Managing SSH credentials securely | Linux has better terminal-based SSH tooling |
| CI/CD troubleshooting (e.g., Cloudflare build failures) | Closer match to Linux-based build servers |
If something breaks silently in Windows, validate it in Linux:
```bash hugo server –buildDrafts
✅ Setup Summary
| Feature | Status |
|---|---|
| Hugo Installed | ✅ |
| PaperMod Theme | ✅ via submodule |
| GitHub Repo | ✅ via SSH |
| Cloudflare Pages | ✅ deployed |
| Custom baseURL | ✅ fixed |
| Token Prompts Fixed | ✅ via SSH |