Hugo loves Github

Hugo loves Github

It’s April 2020. Covid19 forced us to quarantine at home (New York City) and I find myself with some time on my hands. The perfect time to tackle all the nice projects I told myself I would complete some day.

Why not start with a blog? Meet Hugo:

Hugo is a framework for creating static websites, written in GO. It provides a solid foundation for content creation, by taking care of all the infrastructure needed to get a website up and running.

Alright let’s give it a shot.

0) TL;DR

If you are only interested in creating a Hugo based website from a github repo, just run the following commands from this github repository:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

# Create a new EMPTY repo on your github and clone it
git clone https://github.com/<user>/<repo>.git

# Download the deploy.sh script and make it executable
curl -fsSL https://raw.githubusercontent.com/d-asnaghi/hugo-template/master/deploy.sh >> deploy.sh
chmod +x deploy.sh

# Run the script to bootstrap the website
./deploy.sh

# Run the script again to actually publish the website to git pages
./deploy.sh

If you are interested in learning what the script does, the following is an explanation.

1) Build the source

Let’s get started. We need to build the source code of our blog, somehow.

We will need some basic tools first:

• A unix based OS
• homebrew
• git

Now for the fun part

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# install hugo
brew install hugo

# Create a new project in the "website" folder
hugo new site website

# cd into the project's folder
cd website

# Install a theme:
git submodule add https://github.com/panr/hugo-theme-terminal.git themes/terminal

2) Look at the results

Just like that! This is already a fully functional website, smooth right? Let’s see how it looks with

1

hugo server -t terminal

This command will launch a local version of the website on your machine.

Now open a web browser and navigate to localhost:1313 you will see the prototype version of your website come to life with a live preview directly on your computer, one of my favorite features of hugo.

3) Upload your project

Now let’s upload our project online.

At the time of writing, Github is an amazing place to do this, mainly for its github pages feature. Basically Github will allow you to host a static webpage (basically what we are creating with hugo), completely for free at the address https://username.github.io/repo

Pretty cool huh? So, let upload our project to github (you’ll have to create a repo first)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# start a git repo in the site folder
git init

# Add your remote
git remote add origin git@github.com:<username>/<repo>.git

# Commit the project files
git commit . -m "[HUGO] my website"

# Push the changes to the repo
git push

Our project is now online and uses version control, this is going to be super helpful when editing in the future.

4) Host the website on github pages

Now that the source code is online, we want other people to see it as well!

We are going to do this using github pages, specifically, by creating a branch named gh-pages in our repo, where we will place the code hugo generates when translating content we write in markdown to html.

hugo works by generating all the files needed by a real website and placing them in the <project>/public folder on your computer.

You can see this process in action by running hugo -t terminal and looking into the public folder generated.

Now we want to set up the git repo so that every time that we generate new content in public, it will be automatically pushed to the gh-pages branch.

Let’s get to work:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

# First, let's ignore the public folder
echo "public" >> .gitignore
git add .gitignore
git commit -m "[GIT] ignored public folder"

# Initialize the new branch
git checkout --orphan gh-pages
git reset --hard
git commit --allow-empty -m "Initializing gh-pages branch"
git push origin gh-pages
git checkout master

# Set up the public folder to track the new branch
rm -rf public
git worktree add -B gh-pages public origin/gh-pages

Now your public folder will host the gh-branch of your repo, perfect! To publish the changes to the website to that branch we can just:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# cd into the public folder
cd public

# add all changes
git add --all

# commit the changes
git commit -m "[HUGO] deploy website"

# push the changes to the gh-pages branch
git push

Navigate to https://<username>.github.io/<repo> and look at your website!