These are the minimal steps I’ve found to be needed in order to create a blog on GitHub Pages using Hugo (provided Git works already):
Install Hugo (just download it from https://github.com/gohugoio/hugo/releases)
Create an account on GitHub (if you don’t have one)
Create a new repository matching your USERNAME.github.io
Once you have the repositories created (and hugo in your path):
#:> mkdir USERNAME.github.io #:> cd USERNAME.github.io #:> hugo new site .
- Select a Theme from https://themes.gohugo.io/ and then “install” it:
#:> git init #:> git submodule add https://github.com/vaga/hugo-theme-m10c.git themes/m10c
- Edit the config.toml file to set some parameters (and copy an avatar image into the static folder)
baseURL = "https://USERNAME.github.io/" languageCode = "en-us" title = "Your blog's title" theme = "m10c" <-- your theme publishDir = "docs" <-- this one is very important for the last step! [params] author = "Your Name" avatar = "your-avatar.png" <-- put it into the 'static' folder description = "a little description..." menu_item_separator = " - " [[params.social]] name = "github" url = "https://github.com/USERNAME" [[params.social]] name = "twitter" url = "https://twitter.com/USERNAME"
- Create a first post
#:> hugo new posts/my-first-post.md #:> vi content/posts/my-first-post.md <-- add some cool content here!
- Run the Hugo local server and validate that the first version of your site is ready
#:> hugo -D server (with the -D flag you will also see those pages which are still in 'draft' status)
- Once you are happy, generate the “public” content (it’s going to be in the ‘docs’ folder, and don’t forget to set draft: false in the header of your posts, otherwise hugo will not include it in the generated static site, unless you use the -D flag):
- Add everything into version control and perform the first commit and push:
#:> git add . #:> git commit -m "Initial commit" #:> git remote add origin https://github.com/USERNAME/USERNAME.github.io.git #:> git push origin master
- Once everything is in your GitHub repository, go to its ‘Settings’ and under ‘GitHub Pages’ establish the publishing source directory to be the ‘/docs’ folder. After changing this setting GitHub pages says that the site is published but actually I got a 404 for about 2 hours until it finally appeared :)
These steps are also (more or less) explained here: https://gohugo.io/hosting-and-deployment/hosting-on-github/, although I have introduced some simplification (only one repo needed by changing the source directory to be the ‘/docs’ folder).
Note: git does not commit empty folders (which does not seem to be a problem) and when checking out / cloning the repository the recursive flag needs to be used in order to include the theme submodule (otherwise hugo will not work properly)
- In order to checkout the repository from Github (this will create a USERNAME.github.io directory):
#:> git clone --recursive https://github.com/USERNAME/USERNAME.github.io.git
- After introducing any change
#:> hugo server <-- check locally that you are happy with the changes #:> hugo <-- regenerate the static site #:> git add . #:> git commit -m "New cool post added" #:> git push origin master
Your blog should now (or in a while) be accessible at: https://USERNAME.github.io