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:
- Encrypted sub domain of GitHub Pages, for example:
- Unencrypted custom domain, for example:
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.
$ sudo apt install snapd $ snap install hugo $ export PATH=$PATH:/snap/hugo/current/bin
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:
Create the project in GitHub and push:
Create a new ‘mywebsite’ project in GitHub, follow instructions to push to GitHub
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
$ 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"
hugo server -Dand 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
#!/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
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’.
baseURL = "http://mywebsite.org" canonifyURLs = true
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
On github open the project’s settings page and add the Custom domain “mywebsite.org” & click save.
Update your DNS record to point at github.io:
Set the “A” record to point at GitHub’s IP address, 22.214.171.124.
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.