Hugo meets Github Actions
Hugo is blazing fast framwork to build websites. Recently, I migrated my blog from ghost+ghost-buster to hugo and gh pages.
I am assuming that you have git and hugo installed on your machine.
Setting up git repositories -
Github has two types of pages :
- User or Organization pages -
(e.g. https://<USERNAME|ORGANIZATION>.github.io)
- Project pages -
(e.g. https://<USERNAME|ORGANIZATION>.github.io/<PROJECT-NAME>)
Refer github pages documentation for more information.
- Create a
<hugo-blog>
git repository which will contain Hugo website. - Create a
<https://<USERNAME>.github.io>
git repository. This repository will contain content generated by hugo framework. - Open command line and create new hugo site by running
hugo new site <your-site-name>
- Clone your
<hugo-blog>
respository by runninggit clone <REPOSITORY-URL>
- Paste all content from
<your-site-name>
folder to<hugo-blog>
directory - Now, you have brand new hugo website ready, you will need change
config.toml
file accordigly. Excerpt of example config.toml :
# Full example at https://github.com/geekwhocodes/hugo-ink/blob/master/exampleSite/config.toml
baseURL = "http://example.org/"
languageCode = "en-us"
title = "Ink"
theme = "ink"
paginate = 5
copyright = "© Copyright notice"
Adding theme from Hugo Themes -
- You can copy and paste theme in
themes
folder or you can add git submodule - Adding theme as a git submodule - find your choice of theme
(e.g. https://github.com/knadh/hugo-ink)
# 1. Run
bash git submodule add https://github.com/knadh/hugo-ink themes/hugo-ink
# 2. git submodule init
# 3. git submodule update
# Refer https://git-scm.com/book/en/v2/Git-Tools-Submodules for more infomation on submodules
- After running above commands, git will automatically clone theme inside
themes
folder - To run website locally, execute
hugo server or hugo server -t <THEME-NAME>
and make sure everything works on your machine.
Adding Github Action Workflow -
Github actions makes it easy to build, test and deploy your code right from github. It has plenty of actions available to talk to third party platforms. If you want something custom, you can build your own actions.
- Create
.github folder in your <hugo-blog> directory and then create workflows folder under that.
- Create
gh-pages.yml
file under workflows folder, your ``` directory will look something like this: - Github workflow yml, paste this code into
gh-pages.yml
file -
|
|
line 25
Deploy step will push content generated by hugo framework in./public
folder to your<https://<USERNAME>.github.io>
repository, to do this you will need two things- Personal Access Token
- Go to Tokens
- Generate new token, select repo scope and add appropriate note (e.g. hugo-blog access token). Copy that token and save it for later
- Configure Secret in
<<hugo-blog>>
repository -- Go to your
<<hugo-blog>>
repository -> settings -> secrets -> click on ```Add a new secret - Give secret this name - HugoBlogToken and paste Personal Access Token generated from previous step
- Go to your
- Personal Access Token
line 32
You can configure custom domain for your website. Read more informationNow, everything is in place. Push your changes to remote
<<hugo-blog>>
repository. Github Actions will execute gh-pages.yml workflow and publish your website to<<USERNAME/USERNAME.github.io>>
repository.Your brand new website will be avaiable at
https://<<USERNAME>>.github.io
If you need help, reach me on twitter @_ganesh_raskar
Keep learning!