Installation Notes

As a first post, I thought I’d document how I put this blog together, specifically using Hugo + GitHub-Pages. Honestly, this is probably more for my reference that anyone else’s, but whatever. It was good practice in a number of directions, mostly since I don’t know what I’m doing.

Anyway, let’s get started. Everything found below was cobbled together from the following websites.

https://gohugo.io/getting-started/quick-start/
https://themes.gohugo.io/tale-hugo/
https://gohugo.io/hosting-and-deployment/hosting-on-github/

Preliminaries: I’m working on a Mac, and I use homebrew from the command line to install stuff. If you don’t use homebrew (or a Mac), you’ll need to install Hugo differently. Also, I should make clear the fact that I really have no idea what I’m doing, so the following is all “use at your own risk” and my terminology may be way off. You’ve been warned. :)

Step 1.

I already had a Git Hub account, so I logged in to the web version.

Step 2.

I created two new repositories; the first one private which can be left empty:

FishOutOfWater

and the second one public which should initialized with a readme file (I seemed to have problems later with adding the appropriate submodule if I left the repo empty):

joelwatsonfish.github.io

Note: FishOutOfWater will be our repository which holds a bunch of the content Hugo creates for us. But then Hugo will “compile” a static website for us and put it locally in a directory named public. This folder will then be linked with the repository joelwatsonfish.github.io as a submodule in a local directory. It also occurs to me, that I pay for GitHub, so anyone else might not have private repositories. I suspect this doesn’t matter much, other than the fact that maybe people can view things that you are writing in progress. Maybe. Oh, and lastly, one can change FishOutOfWater to anything else, but any other account should change joelwatonfish.github.io to <USERNAME>.github.io in order for everything else to run properly. This makes use of GitHub’s “Pages” for hosting websites.

Step 3.

From a previous attempt, I had installed Hugo. This was done with the following command.

brew install hugo

Step 4.

Decide where the website files are all going to go. These are all files associated to building the site, not just the web pages themselves. I decided on ~/docs/FishOutOfWater, but I didn’t create the directory yet; we let Hugo do that for us in the next step.

Step 5.

Let Hugo create some shit for us, and then move into that directory.

cd ~/docs/
hugo new site FishOutOfWater
cd FishOutOfWater

Step 6.

Initialize the FishOutOfWater directory a repository, and link it with the FishOutOfWater repository on GitHub.

git init
git add .
git commit -m "First commit."
git remote add origin https://github.com/joelwatsonfish/FishOutOfWater
git push -u origin master

Step 7.

Download the desired theme and create a submodule for it. Apparently the benefit of these submodules is that they can be updated via github independently from the parent project. I chose to work with the “tale” theme, so you can change this to something else if you prefer.

git submodule add https://github.com/EmielH/tale-hugo.git themes/tale

Step 8.

Configure the Hugo data for the website. I edited the file ~/docs/FishOutOfWater/config.toml so that it contained the line

theme = "tale"

I also edited two lines so they now read:

baseURL = "https://joelwatsonfish.github.io"
title = "Fish Out Of Water"

Step 9.

Create some new content.

hugo new posts/hello-world.md
cd content/posts

Step 10.

Edit the file “hello-world.md” to say something. Also make sure to change the line “draft: true” to “draft: false”

vim hello-world.md

Step 11.

Check to make sure Hugo can compile everything into a local website.

cd ~/docs/FishOutOfWater
hugo server -D

open a web browser, and put the following in the address bar to navigate here:

http://localhost:1313/

Hopefully you see the site looking and functioning the way it’s supposed to. This is only locally on the computer, so we need to publish this to GitHub (and compile it, I think).

Step 12.

Re-open the terminal in which the last command was run, and hit Ctrl+C to stop the local server.

Step 13.

Check to see if the directory ~/docs/FishOutOfWater/public exists. If it does, then execute the following.

cd ~/docs/FishOutOfWater
rm -rf public

Step 14.

Create a submodule for the directory (public) which will contain the website output from Hugo.

git submodule add -b master https://github.com/joelwatsonfish/joelwatsonfish.github.io.git public

Step 15.

Delete the public directory just created, then run hugo (to compile the site), add, commit, and push all the new content to GitHub

rm -rf public
hugo
cd public
git add .
git commit -m "First commit. Golden Run."
git push origin master
cd ..

Step 16.

Open up a web browser, direct it to the following address.

https://joelwatsonfish.github.io

Step 17.

Making changes to the website follows the following procedure, which will be automated with a script (posted below).

Step 17a.

Edit files locally. Ideally Hugo is used to create new content, which is then modified appropriately.

Step 17b.

Delete the local copy of the website.

cd ~/docs/FishOutOfWater
rm -rf public

Step 17c.

Use Hugo to build the website based off newly edited files; then add, commit, and push to GitHub

hugo
cd public
git add .
git commit -m "Always commit with a message."
git push origin master
cd ..

Step 18.

Automate the update process with the following shell script. Create a file called ~/docs/FishOutOfWater/deploy.sh detailed below, change permisions so it can be executed, and execute it with the command ./deploy.sh

#!/bin/bash

echo -e "\033[0;32mDeploying updates to GitHub...\033[0m"

# Build the project.
hugo # if using a theme, replace with `hugo -t <YOURTHEME>`

# Go To Public folder
cd public
# Add changes to git.
git add .

# Commit changes.
msg="rebuilding site `date`"
if [ $# -eq 1 ]
  then msg="$1"
fi
git commit -m "$msg"

# Push source and build repos.
git push origin master

# Come Back up to the Project Root
cd ..

Step 19.

Make some changes to the site. I added another post with the command hugo new posts/installation-notes.md and then ran my newly written shell script to update the website.

./deploy.sh

Step 19.

Take over the world.