A beginner’s tutorial for building a static website on Github with Hugo.

Finally, my website is live. 🙂 I am fairly new to Github and markdown, so I thought I’d write down how I did it. This blog is for complete beginners (and Mac users).

Table of Contents

Step 1: Install essentials

First, you need to install Hugo, which is a generator for static websites. Once everything is set up, you can simply write blogs as markdown files and Hugo will automatically generate all the html pages for you. Cool.
A detailed tutorial for Hugo can be found here. Install Homebrew, and then:

brew install hugo

You will also need Git and a SSH key for Github. Here are some helpful tutorials for generating a key and adding it to Github.
Once Hugo is installed, you can create a new directory for the site:

hugo new site Yue_blog

Pick a theme for your site (I selected the theme tranquilpeak). cd into the directory, and add the theme.

cd Yue_blog
git init
git submodule add https://github.com/kakawait/hugo-tranquilpeak-theme.git themes/hugo-tranquilpeak-theme

Step 2: Build a site locally

The quickest way to get a working site is to copy everything from the exampleSite folder provided by the theme. 🙂

# Start from the site directory
pwd # get path to this directory
cd themes/hugo-tranquilpeak-theme/exampleSite/
cp -a * /Path/to/site/directory/Yue_blog
# Get back to the site directory
cd ../../..

Similarly, update the files in the layouts and the archetypes folders with the provided layouts and archetypes from the theme.

cd themes/hugo-tranquilpeak-theme/layouts/
cp * /Path/to/site/directory/Yue_blog/layouts
cd themes/hugo-tranquilpeak-theme/archetypes/
cp * /Path/to/site/directory/Yue_blog/archetypes

Now, try the following command and see what happens:

hugo server

Open a web browser and navigate to localhost:1313. exampleSite

Step 3: Customize your site

Your new website is working (locally). But it’s not quite yours yet. Better add some original content. From now on, all you need to do is to edit the configuration file config.toml, and stuff in the content folder. I will provide a few examples in the following blog post.

Step 4: Create Github respositories

You will need to create two repositories, one (BLOG) will contain all the source files, and the other one (USERNAME.github.io) will contain the generated website. A detailed tutorial can be found in here.
Link the BLOG repository to your local directory.

cd Yue_blog
git remote add origin https://github.com/YueYvetteHao/Yue_blog.git

Sync the local and remote repositories

git pull origin master

Remove the public folder and add it back as a git submodule.

rm -rf public
git add .
git commit -m "updates ..."
git push origin master
git submodule add -b master git@github.com:YueYvetteHao/YueYvetteHao.github.io.git public

Step 5: Deploy - hello world!

Get the deploy script here and save it in the BLOG repo. Run the shell script to compile the markdown files into html, git add and git commit to the USERNAME.github.io repo:

sh deploy.sh

Done! The website is now running. 🙂
This is how I built my first personal website. I hope this tutorial is helpful!

Update 10/05:
I recently migrated my website to netlify, which makes continuous deployment possible. Now after I push changes to the BLOG repository on github, the site will be automatically deployed within seconds. Even cooler. :)