A personal website is an excellent platform for sharing blog posts, documenting what you’ve learned, and showcasing your skills. In this post, I’ll walk through how I built my own website using Hugo and deployed it for free using GitHub Pages.

Hugo Link to heading

Hugo is a fast and flexible static site generator written in Go. It’s designed to build websites quickly and efficiently by converting content written in Markdown into fully functional HTML pages. Hugo is popular among developers and content creators for its speed, ease of use, and support for themes, taxonomies, and customizable templates. It’s an excellent choice for blogs, personal websites, and documentation sites, especially when paired with version control and free hosting platforms like GitHub Pages. Here is a general workflow:

Hugo website

Install Hugo. Refer to Offical Guide. For me I use snap on Ubuntu 22.04:
```
 $ sudo snap install hugo
```

Create a New Hugo Site.


 $ hugo new site my-website
 $ cd my-website

Add a Theme. Choose a theme from Hugo Themes and add it:


 $ git submodule add https://github.com/luizdepra/hugo-coder.git themes/hugo-coder
 $ echo 'theme = "hugo-coder"' >> config.toml

Create Content Add your first post or page, by directly adding markdown file or command line:
```
 $ hugo new posts/my-first-post.md
```
Preview the Site Locally
```
 $ hugo server -D
```

Git page deployment Link to heading

This project is hosted using GitHub Pages, which requires an index.html file as the entry point for rendering the site. When using Hugo, this file is automatically generated—along with the rest of the site content—inside the public/ directory by running the hugo command.

However, GitHub Pages does not directly serve files from the public/ directory unless they are exposed correctly. To address this, I explored two deployment strategies:

Deploying the public/ folder to a dedicated branch – typically gh-pages.
Automating deployment with GitHub Actions – to build the site and push the contents of public/ to the appropriate branch during each update.

First, initialize a Git repository in the root directory (my-website), then add, commit, and push the code to GitHub.

branch deployment manually

Hugo builds the site into public/ folder, we could push only the contents of public/ to a new ‘gh-pages’ branch for GitHub Pages to serve. Here is the step-by-step instructions:

Build Your Hugo Site
```
$ hugo
```
Run it from the root of your Hugo project, this generates your static site in the public/ directory — including index.html.

Create and Push the gh-pages Branch


 $ cd public
 // Initialize a new Git repo (separate from your main repo):
 $ git init
 $ git remote add origin https://github.com/<your-username>/<your-repo>.git //Set your GitHub repo as the remote
 $ git checkout -b gh-pages  // Create the gh-pages branch
 $ git add .
 $ git commit -m "Initial deploy to gh-pages"
 $ git push -f origin gh-pages

The -f is needed because this is a fresh, unrelated branch. Another cleaner way could be ‘git checkout –orphan <your-branch>’, this command creates a new branch without any commit history from the current branch (in this case, main) and sets it up as the gh-pages branch, the workflow is similar:


 $ git checkout --orphan gh-pages
 $ git rm -rf .            # Remove all files from the `gh-pages` branch
 $ cp -r public/* .        # Copy everything from `public/` to the root of `gh-pages`
 $ git add .               # Add the new static files
 $ git commit -m "Deploy site to GitHub Pages"
 $ git push -f origin gh-pages

Configure GitHub Pages
Go to your repository on GitHub. Click Settings → Pages. Under Source, select:
- Branch: gh-pages
- Folder: / (root) Click Save.

GitHub will build your site from the contents of the gh-pages branch. Now checkout the website: https://<your-username>.github.io/<your-repo>/. Note that everytime you make updates, run:


$ hugo                    # Rebuild the site
$ cd public
$ git add .
$ git commit -m "Update site"
$ git push -f origin gh-pages
$ cd ..

You could automate this with a script or GitHub Actions (check the second option).

Automated deployment using Github Actions

Go to Settings → Pages, choose ‘Source’ under ‘Build and deployment’ section, and github will provide an official static site deployment template, here is the customized version for Hugo, so it:

Builds the site using Hugo, and
Uploads the contents of the public/ folder, not the entire repo.