In this article, I would share my experiences and the steps I took when building a personal website on GitHub Pages using Hugo. To build a personal website, you don’t need to have knowledge other than writing Markdown. It’s simple, let’s go!

You can find my Github repository for this blog here.

Step 1: Install Git

Git is a free and open source distributed version control system designed to handle everything from small to very large projects with speed and efficiency.

Git can be installed on macOS, Windows and Linux. In fact, Git comes installed by default on most macOS and Linux machines. You can read and follow the Git installation instructions to install Git.

On my macOS, Git is already installed. You can easily check by opening the command prompt “Terminal” and run the following command to verify Git was installed.

git version  ##check git version

Step 2: Install Hugo

Hugo is a fast static website generator written in Go. Unlike systems that dynamically build a page with each visitor request, Hugo builds pages when you create or update your content. Hugo takes data files, configuration, templates for layouts, static files, and content written in Markdown and renders a static website.

Hugo can be installed on macOS, Windows, and Linux with the Hugo installation instructions. And you don’t need to install Go to enjoy Hugo.

On my macOS, I first installed Homebrew by running the following command in Terminal. (You can find other installation options.)

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"

You can then verify Homebrew is installed by

brew help

After that, run the followng command to install Hugo.

brew install hugo

When finished, verify that hugo runs correctly by

hugo version  ##check hugo version

Step 3: Create a Hugo Site

Find a place to store the Hugo site folder. I put it in my desktop by

cd desktop  ##change directory

Then create a new Hugo site by

hugo new site blog  ##blog is the filename

Step 4: Customize Your Hugo Site

Here you can find numerous Hugo Themes. You can choose one and copy the download address. For example, I chose the Tranquilpeak.

  1. Go to your Hugo site directory.
cd blog  ##change directory
  1. Download the Hugo theme.
git clone https://github.com/kakawait/hugo-tranquilpeak-theme.git themes/tranquilpeak
  1. Copy the configuration file that comes with the theme and replace the default configuration file with it.
cp themes/tranquilpeak/exampleSite/config.toml .

Note: please be careful to include . at the end of the command line.

  1. Edit the configuration file config.toml

You need to change baseURL = "your_github_name.github.io" and theme = "tranquilpeak". Here, you should replace your_github_name with exactly your github name. You can use vi in Terminal or use VS Code to do this.

Take vi for example.

vim config.toml  ##open and edit file

After editing the file, press esc and then input :wq to save the changes and exit vi.

Step 5: Write a new post

  1. Create a folder to store posts.
mkdir content/post  ##create a folder
  1. Create a new post.
hugo new content/post/first.md  ##"first.md" is the file name of the new post.
  1. Edit the newly created post and add some content.

Step 6: Preview your site

If you are ready, start the Hugo server.

hugo server -D

You can preview your site at http://localhost:1313/.

Step 7: Build your Hugo site

If you are satisfactory with the preview, build your site by

hugo

After execution, a “public” directory will be added. This directory is a static file. Just upload the files in this folder.

Step 8: Connect to Github

Set global user name and user email with Github.

git config --global user.name "your_github_name"
git config --global user.email "your_github_email"

Step 9: Create a new Github repository

  1. Create a Github account.

  2. Create a new repository named “your_github_name.github.io”, where your_github_name is your username on GitHub. Please be careful not to initialize this repo with a README.

Step 10: Publish your Hugo Site to Github Pages

cd public  ##go to the directory to publish
git init  ##initialize a git repo
git add .  ##add all edited files
git commit -m 'first commit'  ##'first commit' is the commit message
git remote add origin git@github.com:your_github_name/your_github_name.github.io.git  ##link to git repo
git push -u  origin master  ##push your changes

After that, you are done! Go to https://your_github_name.github.io to see your new site.