Hugo website hosted on GitHub Pages

August 2, 2017


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.

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 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 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.

© 2018 Keith P | Follow on Twitter | Git