As we know from an earlier post this site is a statically generated Hugo site hosted on GitHub Pages, so I thought it would be interesting to do a post detailing the steps involved in getting the site up and running. These instructions should work on a linux based OS or on MacOS.
Firstly, what will we need. You will need to install git, hugo and have a GitHub account.
The first thing I did was log into the GiHub site and create two repos, one for hosting the site and one source repo as follows
Next, we open a terminal window, create a folder for the project and change into that new folder
mkdir projectname cd projectname
Now we can use Hugo to build a new skeleton site, then change into the site directory
hugo new site sitename cd sitename
Time to create our local git repository for our site source
git init git remote add origin <sitename_source url> git add . git commit -m "Initial commit"
Whatever Hugo theme you choose will have installation instructions that you can follow in order to add it to your new site. I chose the mainroad theme that I added by adding a git submodule.
git submodule add https://github.com/vimux/mainroad.git themes/mainroad
Hugo themes will typically come with an example site so I found that the best thing to do is to copy this into the main directory of my site and then update the config.toml file and add my content.
cp -r themes/mainroad/exampleSite/* .
This is where you now make your changes to suit your content. The best themes should have a guide on how to update the config.toml file. Any images you have will go into the static folder and your posts will go into content. Once you have added your content you can build the site locally and check it out.
hugo server -D
Once you are happy with how the site looks locally, you can add the theme and content to you source repository and push it to GitHub
git add . git commit -m "added theme and content" git push --set-upstream origin master
Now we can build our site and push it out to the repository in which we will actually be hosting the site
hugo cd public git init git remote add origin <sitename url> git add . git commit -m "Initial commit" git push --set-upstream origin master
Once pushed, go to your site repository, then settings and pages. Set Source to Branch:master, then you can test it by clicking the “published at” link.
Congratulations, you now have a Hugo generated site hosted on GitHub Pages.
If you have a custom domain that you want to use, you will need a CNAME file in the root of your GitHub Pages repository containing the domain, so mine just contains
Next, you will need to log into your account with your domain registrar and add four A records with host @ and the following IP addresses
184.108.40.206 220.127.116.11 18.104.22.168 22.214.171.124
You will also need to add a CNAME record with the host “www” and the value of
<your github account>.github.io.
Note the last . is required.
Finally, go back to your GitHub Pages repository, go to settings, then pages and add your domain under Custom Domain; now you can wait for DNS to propagate.
As a bonus, here is the script I run from the site root directory when I add a new post to automate everything
#!/usr/bin/env bash set -e printf "\033[0;32mDeploying updates to GitHub...\033[0m\n" git add . git commit -m "Add site files" git push --set-upstream origin master hugo cd public git add . msg="rebuilding site $(date)" if [ -n "$*" ]; then msg="$*" fi git commit -m "Add site files" git push --set-upstream origin master