Hugo website hosted on GitHub Pages

How we created a static website using Hugo and hosted it on GitHub Pages, for free.

With Hugo + GitHub Pages you get:

• Static website generator.
• Auto-deploy on checkin.
• Free hosting.
• Custom domain (not secured with SSL/TLS encryption).

With GitHub Pages your URL options are:

1. Encrypted sub domain of GitHub Pages, for example: https://mygitname.github.io/mywebsite.
2. Unencrypted custom domain, for example: http://mycustomdomain.

If you want to use a custom domain and SSL/TSL encryption, consider using GitLab instead: see blog post [Hugo website hosted on GitLab Pages] (/post/hugo-website-on-gitlabpages/).

We are running on Linux, your commands might differ. In the following sustitute ‘mywebsite’ with your project name.

Part 1: Create a new Hugo website:

You might want to look at Hugo - getting-started.

Here are the steps we took.

Steps:

1. Install Hugo:

   $ sudo apt install snapd
   $ snap install hugo
   $ export PATH=$PATH:/snap/hugo/current/bin
   

2. Create a new site:

   Skip this step if you already generated your Hugo site (for example you converted Wordpress to Hugo).

   $ hugo new site mywebsite
   $ cd mywebsite
   $ git init
   

Part 2: Deploy to GitHub & GitHub Pages:

Steps:

1. Create the project in GitHub and push:

   Create a new ‘mywebsite’ project in GitHub, follow instructions to push to GitHub

2. Setup deployment to GitHub Pages:

   This is a one off step to prepare for easy deployment.

   First you will need the latest version of git, otherwise you could get an error on using $ git worktree:

   $ sudo add-apt-repository ppa:git-core/ppa
   $ sudo apt-get update
   $ sudo apt-get install git
   -> git version is now 2.13.0
   

   We followed the [Preparations for gh-pages Branch] (https://gohugo.io/hosting-and-deployment/hosting-on-github/) which causes GitHub Pages to automatically detect changes and deploy the site off the gh-pages branch:

   $ echo "public" >> .gitignore
   $ 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
   $ rm -rf public
   $ git worktree add -B gh-pages public origin/gh-pages
   

   Choose a Hugo theme, in this case we use the [ananke theme] (https://themes.gohugo.io/gohugo-theme-ananke/) at https://github.com/budparr/gohugo-theme-ananke.git

   $ git submodule add https://github.com/budparr/gohugo-theme-ananke.git themes/ananke
   $ echo 'theme = "ananke"' >> config.toml
   
   

   Review and update /config.toml:

   baseURL = "https://mygitname.github.io/mywebsite"
   canonifyURLs = true
   theme = "ananke"
   

   Run hugo server -D and review the site at http://localhost:1313/.

   Commit and push changes on the master branch.

   Add this ‘publish_changes.sh’ file to the ‘mywebsite’ directory to generate and push content on the gh-pages branch:

   #!/bin/sh
   
   #DIR=$(dirname "$0")
   
   #cd $DIR/..
   
   if [[ $(git status -s) ]]
   then
       echo "The working directory is dirty. Please commit any pending changes."
       exit 1;
   fi
   
   echo "Deleting old publication"
   rm -rf public
   mkdir public
   git worktree prune
   rm -rf .git/worktrees/public/
   
   echo "Checking out gh-pages branch into public"
   git worktree add -B gh-pages public origin/gh-pages
   
   echo "Removing existing files"
   rm -rf public/*
   
   echo "Generating site"
   HUGO_ENV="production" hugo
   
   echo "Updating gh-pages branch"
   cd public && git add --all && git commit -m "Publishing to gh-pages (publish.sh)"
   
   echo "pushing to publish"
   git push origin gh-pages -f
   
   

3. Deploy changes to GitHub Pages:

   Now that the above steps are done, from now on deploying changes is done by pushing your commit and publishing to the gh-pages branch with these 2 commands:

   $ git push
   $ sh publish_changes.sh
   

   Verify the deployment worked by opening you browser at your GitHub project page: https://mygitname.github.io/mywebsite.

Part 3: Use your own custom domain ( Optional ):

Here is how we configured our DSN, GitHub and source code to use our own custom domain ‘mywebsite.org’.

Steps:

1. Update /config.toml:

   baseURL = "http://mywebsite.org"
   canonifyURLs = true
   

2. Add a CNAME file in the mywebsite directory, push and publish:

   $ cd mywebsite
   $ echo "mywebsite.org" >> CNAME
   $ git commit -m "Adds custom domain"
   $ git push
   $ sh publish_changes.sh
   
   

3. On github open the project’s settings page and add the Custom domain “mywebsite.org” & click save.

4. Update your DNS record to point at github.io:

   Set the “A” record to point at GitHub’s IP address, 192.30.252.153.

5. Wait a short while, then verify its working at: http://mywebsite.org

The only slight disappointment is its not possible to use an SSL/TLS certificate with a custom domain configured.