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


  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:


  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

    $ git submodule add themes/ananke
    $ echo 'theme = "ananke"' >> config.toml

    Review and update /config.toml:

    baseURL = ""
    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 ‘’ file to the ‘mywebsite’ directory to generate and push content on the gh-pages branch:

    #DIR=$(dirname "$0")
    #cd $DIR/..
    if [[ $(git status -s) ]]
        echo "The working directory is dirty. Please commit any pending changes."
        exit 1;
    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 ("
    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

    Verify the deployment worked by opening you browser at your GitHub project page:

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


  1. Update /config.toml:

    baseURL = ""
    canonifyURLs = true
  2. Add a CNAME file in the mywebsite directory, push and publish:

    $ cd mywebsite
    $ echo "" >> CNAME
    $ git commit -m "Adds custom domain"
    $ git push
    $ sh
  3. On github open the project’s settings page and add the Custom domain “” & click save.

  4. Update your DNS record to point at

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

  5. Wait a short while, then verify its working at:

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

© 2020 Keith P | Follow on Twitter | Git