Introduction

I thought to build a personal website several times but failed to do it. On one weekend in December 2022, I decided to complete this website project before the new year 2023. I started by searching “create a personal website” on youtube.The algorithm recommends videos with Hugo. My first thought 🤔: since when Hugo Boss started to build websites instead of selling expensive clothes 😄. Some videos promise to do it with Hugo within 10 minutes. That’s great. I was excited about it.

The main reasons I want to have a personal website are:

• a place to write blogs: I continue learning new skills and technologies. I want to summarize and document them by writing blogs.
• digital portfolio: showcase my past projects and share knowledge.

Hugo is a static site generator that allows website authors to create blogs or pages in Markdown. So it’s suitable for me. You can host it freely in Github pages. What’s more, there are hundreds of Hugo themes ready to use for various purposes. Sounds cool? And guess what? I spent 10 minutes watching that youtube tutorial but the rest of the weekend to figure it what was wrong with one error by deploying. I will share my guide so that you don’t have to go through all the pain I went through.

Prerequisites

Hugo is pretty cool and much easier than building everything from scratch. You are expected to know some basic knowledge of HTML, command line, git, etc. It requires investing time to learn some things if you don’t know them all.

• Installation of Hugo
  Refer to the official documentation Installation
• Basic knowledge of Markdown or HTML, CSS, and command line
  Both HTML and Markdown have supported content formats.
• One text editor, e.g. VS code
• A Github account
• Knowledge of Git
  Git is required to install a theme as a Git submodule, access commit information from a local repository, and host your site.

Choose a Hugo Theme

You can find one suitable Hugo theme hier. Either for a portfolio or company, there are plenty of template themes to choose from. I’ve chosen hugo tranquilpeak theme.

Create a project

1. Create a folder on your local PC. If you want to use any hugo theme, you can do it either with git clone or git submodule. git submodule makes it easier to update this theme if you have your Hugo site in git as well.

git submodule is recommended. You can always copy the layouts to overwrite the default theme.

# Make a new directory
mkdir hugo-site
# Create a new hugo site 
hugo new site my-hugo-site
# Go to the root of your hugo site project
cd my-hugo-site
# Initialize an empty Git repository in the root direcotry
git init
# Add a template theme into themes directory
# Please change the github url to your desired theme url
git submodule add https://github.com/kakawait/hugo-tranquilpeak-theme.git themes/hugo-tranquilpeak-theme
# Add a line about theme in the config file
echo "theme = 'hugo-tranquilpeak-theme'" >> config.toml
# Start Hugo's developement server to view the site, -D, --buildDraftinclude content marked as draft.
hugo server -D

Create your first content

hugo new posts/my-first-blog.md

You can use markdown language to write content.

Deploy in Github

A lot of youtube tutorials don’t talk about the public folder at all. After reading and studying a lot of materials, I summarized two methods to deploy on Github Page.
The first one with the public is recommended. I wrote down the second method for reference.

1. Method:
   In this method, you will prepare two Github repositories. One public repo is for the publishing website and one private repo is for the content.
   For example,

• public repo called your-user-name-in-github.github.io.
• private repo called blog

In config.toml file change baseURL = “https://your-user-name-in-github.github.io/".

# At the root directory of the website project
# publish website and generate public folder
hugo
# Enter public directory
cd public
# Initialize an empty git repository
git init
# Change branch to main
git branch -M main
# Add, commit all the changes in the public folder to remote github repository
git add .
git commit -m "first commit"
git push -u origin main

If everything works well, you will see your website running on https://your-user-name-in-github.github.io.

2. Method:
   In the root folder create the folders called .github/workflows. Then create a file called gh-pages.yml. Then copy the following content to the yml file. Then git push all the changes in the root folder to github repository.

name: github pages

on:
  push:
    branches:
      - main  # Set a branch that will trigger a deployment
  pull_request:

jobs:
  deploy:
    runs-on: ubuntu-22.04
    steps:
      - uses: actions/checkout@v3
        with:
          submodules: true  # Fetch Hugo themes (true OR recursive)
          fetch-depth: 0    # Fetch all history for .GitInfo and .Lastmod

      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: 'latest'
          # extended: true

      - name: Build
        run: hugo --minify

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        if: github.ref == 'refs/heads/main'
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./public

from github-pages-action

Debugging

You did all the steps above and wait for the most exciting moment when the web is online. If it doesn’t work as you expected, you can do the following checks.

• In config.toml, do you add a line about the theme and change baseURL?
• If the theme doesn’t appear, did you use git clone the theme under the themes directory? If yes, don’t forget to remove .git from the themes directory.

Next Steps

Your website is online and you can publish new content. You might want to add more functions, like comments on your posts, or data tracking via google analytics.
In my next blog, I will write about these.

Reference

• Hugo official doc
• Github pages

Please visit my home page to find more contents.