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

  1. Install Hugo (just download it from

  2. Create an account on GitHub (if you don’t have one)

  3. Create a new repository matching your

  4. Once you have the repositories created (and hugo in your path):

#:> mkdir
#:> cd
#:> hugo new site .
  1. Select a Theme from and then “install” it:
#:> git init
#:> git submodule add themes/m10c
  1. Edit the config.toml file to set some parameters (and copy an avatar image into the static folder)
baseURL = ""
languageCode = "en-us"
title = "Your blog's title"
theme = "m10c" <-- your theme
publishDir = "docs" <-- this one is very important for the last step!

  author = "Your Name"
  avatar = "your-avatar.png" <-- put it into the 'static' folder
  description = "a little description..."
  menu_item_separator = " - "
    name = "github"
    url = ""
    name = "twitter"
    url = ""
  1. Create a first post
#:>  hugo new posts/
#:>  vi content/posts/ <-- add some cool content here!
  1. 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)
  1. 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):
#:> hugo
  1. Add everything into version control and perform the first commit and push:
#:> git add .
#:> git commit -m "Initial commit"
#:> git remote add origin
#:> git push origin master
  1. 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:, 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)

  1. In order to checkout the repository from Github (this will create a directory):
#:> git clone --recursive
  1. 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: