How to Setup Hugo and Github Pages

As I have promised in a tweet to Edgar here is short explanation on how to setup Hugo and Academic theme.

Table of Contents

Below you can find TLDR; descriptions.

Download and install GIT

For windows you can get it from here:

After a few next, next clicks you will have Git installed. Congratz!

Download and setup hugo binary (extended)

For those interested in docs you can find them here:

Or visit this link for the latest release

search for (ctrl+f):


Download it and extract it where you want.

Set PATH Enviroment Variable to point to the extracted binary.

To test it you can ask for a hugo version. Open CLI (Powershell or CMD) and type “hugo version”. You will get output like this:

PS D:\Hugo\bin> hugo version
Hugo Static Site Generator v0.59.0/extended windows/amd64 BuildDate: unknown

Create a new site

Execute this in CLI where [my_site_name] is arbitrary name (in our example “demo-site”)

PS D:\Hugo\Sites> hugo new site [my_site_name]

Congratulations! Your new Hugo site is created in D:\Hugo\Sites\demo-site.

Just a few more steps and you are ready to go:

1. Download a theme into the same-named folder.
   Choose a theme from or
   create your own with the "hugo new theme <THEMENAME>" command.
2. Perhaps you want to add some content. You can add single files
   with "hugo new <SECTIONNAME>\<FILENAME>.<FORMAT>".
3. Start the built-in live server via "hugo server".

Visit for quickstart guide and full documentation.

After that you will get a folder with everythign ready to start.

Add .gitignore file to your new hugo site

add .gitignore content from

GIT time

For next steps you will need to create two repositories under you github account. One will hold markdown content (.md files) and it will be a private repo. And other one will hold generated static site that resides in /public folder and it will be public repo.

Init a repo for hugo (repo for markdown)

git init
git add .
git commit -m "Initial commit"

Find the URL of the repository the will hold markdown content files and add it to newly created git repo.

git remote add origin [markdown-content-repo-URL]

add submodule for public folder

git submodule add -b master<USERNAME>/<USERNAME> public

Add Academic theme as git submodule

git submodule add themes/hugo-academic

Copy example demo site

You can find it here:

Just copy the content to your demo-site and run a local site via hugo command (See below).

CLI usage

To get you started faster hare are some usefull commands.

example of command to create new post

hugo new post/2019/10/how-to-setup-hugo-and-github-pages

run local site

hugo server -D

generate site in /public


update of submodules

git submodule foreach git pull origin master
Petar Šlat
Petar Šlat
Software engineer / SRE / DevOps / AWS Cloud Architect

My current interests are in automation and optimiztions in computing. Slow is smooth, Smooth is fast.