Build a Personal Website with Hugo and GitHub Pages

A beginner-friendly guide to building a portfolio website with Hugo and deploying it to GitHub Pages for free.

Introduction

In this guide, you'll learn how to create a personal portfolio website using Hugo (a fast static site generator) and host it for free on GitHub Pages. No previous experience with web development is required!

What You'll Build

A clean, professional portfolio website with:

A landing page with your profile
A blog section for your posts
Mobile-friendly design
Fast loading times

PREPARATION: What You Need First

Before we start, let's get everything ready on your computer.

1. Install Git (Version Control)

Git helps track changes to your website and upload it to GitHub.

Windows Users:

Download from: https://git-scm.com/download/win
Run the installer with default settings

Mac Users:

Download from: https://git-scm.com/download/mac
Or install with Homebrew: brew install git

To verify installation: Open Terminal (Mac) or Command Prompt (Windows) and type:

git --version

If you see a version number, Git is installed correctly!

2. Install Hugo (Website Builder)

Hugo is the tool that converts your content into a website.

Windows Users:

Download from: https://gohugo.io/installation/windows/
Follow the installation instructions

Mac Users:

Install with Homebrew: brew install hugo

To verify installation:

hugo version

3. Create a GitHub Account

If you don't have one yet:

Go to github.com
Click "Sign up"
Follow the registration process

STEP 1: Create Your GitHub Repository

First, let's create a home for your website on GitHub.

Log in to your GitHub account
Click the + icon in the top right corner
Select New repository
Repository name: MUST be exactly [YOUR_USERNAME].github.io (replace [YOUR_USERNAME] with your actual GitHub username)
- Example: If your username is johndoe, name it johndoe.github.io
Set Visibility to Public
DO NOT check "Add a README file"
Click Create repository

Your repository is now ready! Keep this page open - we'll need it later.

STEP 2: Set Up Your Local Project

Now let's create the website on your computer.

Open Terminal (Mac) or Command Prompt (Windows)
Navigate to where you want to create your project (e.g., cd Documents)
Run these commands one by one:

# Create a new Hugo site
hugo new site my-portfolio
 
# Enter the new folder
cd my-portfolio
 
# Initialize Git repository
git init
 
# Connect to your GitHub repository
# Replace '[YOUR_USERNAME]' with your actual GitHub username
git remote add origin https://github.com/[YOUR_USERNAME]/[YOUR_USERNAME].github.io.git

You now have a basic Hugo project on your computer!

STEP 3: Install a Theme

A theme controls how your website looks. We'll use PaperMod, a clean and modern theme.

In your terminal (while inside the my-portfolio folder), run:

git submodule add --depth=1 https://github.com/adityatelange/hugo-PaperMod.git themes/PaperMod

This downloads the PaperMod theme into your project.

STEP 4: Configure Your Website

Now let's tell Hugo how to build your website.

Open the hugo.toml file in your project folder
Replace all content with this:

baseURL = "https://[YOUR_USERNAME].github.io/"
languageCode = "en-us"
title = "My Portfolio"
theme = "PaperMod"
 
# IMPORTANT: This tells Hugo to put the website in a "docs" folder
publishDir = "docs"
 
[params]
  description = "My personal blog and portfolio"
  author = "Your Name"
 
  [params.profileMode]
    enabled = true
    title = "Hi, I'm Your Name!"
    subtitle = "Passionate developer creating amazing digital experiences. Love to explore new technologies and build innovative solutions that make a difference."
 
# Social Links - GitHub and LinkedIn only
  [[params.socialIcons]]
    name = "github"
    url = "https://github.com/[YOUR_USERNAME]"
  [[params.socialIcons]]
    name = "linkedin"
    url = "https://linkedin.com/in/[YOUR_USERNAME]"
 
# Menu Navigation
[menu]
  [[menu.main]]
    name = "Blog"
    url = "/posts/"
    weight = 1
  [[menu.main]]
    name = "Projects"
    url = "/projects/"
    weight = 2

Important: Replace the placeholders with your actual information:

Replace [YOUR_USERNAME] with your actual username in the baseURL, GitHub social link, and LinkedIn social link
Replace "Your Name" with your actual name

STEP 5: Create Your First Content

Let's add some content to your website. We'll create one blog post and one project page.

Create a Blog Post

In your terminal, run:

hugo new posts/my-first-post.md

Now open the file content/posts/my-first-post.md and replace its content with:

---
title: "My First Blog Post"
date: 2025-11-20
draft: false
tags: ["personal", "introduction"]
---
 
## Welcome to My Blog!
 
This is my first blog post. I'm excited to share my journey with you!
 
### Why I Started This Blog
 
I created this website to:
 
- Document my learning journey
- Share projects I'm working on
- Connect with other developers
- Keep track of my progress
 
### What's Next
 
I'll be writing about:
 
- Web development tips and tricks
- Projects I'm building
- Things I'm learning
- My experiences in tech
 
Stay tuned for more content!

Create a Project Page

Now let's create a page to showcase your projects:

hugo new projects/my-first-project.md

Open the file content/projects/my-first-project.md and replace its content with:

---
title: "My First Project"
date: 2025-11-20
draft: false
tags: ["project", "web", "beginner"]
---
 
## Project Overview
 
This is a showcase of my first project that I'm proud of!
 
### What It Does
 
Briefly describe what your project does:
 
- What problem does it solve?
- Who is it for?
- What makes it special?
 
### Technologies Used
 
- HTML
- CSS
- JavaScript
- [Add any other technologies you used]
 
### Challenges and Solutions
 
Share some challenges you faced and how you solved them:
 
1. **Challenge:** Describe a problem you encountered
   **Solution:** Explain how you fixed it
 
2. **Challenge:** Another challenge you faced
   **Solution:** Your approach to solving it
 
### What I Learned
 
- [Skill or concept you learned]
- [Another thing you learned]
- [One more learning takeaway]
 
### Future Improvements
 
- [Feature you want to add]
- [Enhancement you're planning]
- [Ideas for version 2.0]
 
### Project Link
 
[View Live Demo](https://example.com) | [GitHub Repository](https://github.com/[YOUR_USERNAME]/project-name)
 
---
 
_Note: Replace the example links with your actual project links when you have them!_

STEP 6: Build and Upload Your Website

Now let's turn your content into a real website and upload it to GitHub.

In your terminal (while in the my-portfolio folder), run these commands:

# Build your website (creates HTML files)
hugo
 
# Add all files to Git
git add .
 
# Save your changes with a message
git commit -m "First version of my website"
 
# Upload to GitHub
git branch -M main
git push -u origin main

You might be asked for your GitHub username and password during the push process.

STEP 7: Activate GitHub Pages

This is the final step to make your website live on the internet!

Go back to your repository on GitHub
Click the Settings tab
In the left sidebar, click Pages
Under "Build and deployment":
- Source: Select "Deploy from a branch"
- Branch: Select "main"
- Folder: Select "/docs" (this is why we set publishDir = "docs" earlier)
Click Save

Wait 1-2 minutes for GitHub to process your website. Then visit https://[YOUR_USERNAME].github.io/ (replace [YOUR_USERNAME] with your actual username) to see your live website!

Updating Your Website

Whenever you want to update your website:

Add or edit content in your my-portfolio folder
Run these commands in your terminal:

hugo                  # Build the updated website
git add .             # Stage all changes
git commit -m "Update website content"  # Save with a message
git push              # Upload to GitHub

Your website will automatically update within a few minutes!

Congratulations! 🎉

You now have a personal portfolio website that:

Looks professional on all devices
Loads incredibly fast
Is completely free to host
Can be easily updated

Next Steps

Consider adding:

An About page (hugo new about.md)
Project showcase pages
More blog posts
Social media links

Remember: Your website URL is https://[YOUR_USERNAME].github.io/ (replace [YOUR_USERNAME] with your actual username).

Happy building!