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.

You will have it by the end of the weekend

— Petar Šlat (@pekiZG) October 24, 2019

Below you can find TLDR; descriptions.

Download and install GIT

For windows you can get it from here: https://git-scm.com/

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: https://gohugo.io/getting-started/installing#windows

Or visit this link for the latest release https://github.com/gohugoio/hugo/releases

search for (ctrl+f):

hugo_extended_[SEM_VERSION]_Windows-64bit.zip

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 https://themes.gohugo.io/ 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 https://gohugo.io/ 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 https://www.gitignore.io/api/hugo

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 git@github.com:<USERNAME>/<USERNAME>.github.io.git public

Add Academic theme as git submodule

git submodule add https://github.com/gcushen/hugo-academic.git themes/hugo-academic

Copy example demo site

You can find it here: https://github.com/gcushen/hugo-academic/tree/master/exampleSite

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

hugo

update of submodules

git submodule foreach git pull origin master