Hugo is one of the most popular open-source static site generators. Static sites can be created with Markdown files using Hugo.

This article outlines the steps to generate a blog(static site) using Hugo and hosting it on GitHub.

Installing Hugo

Hugo is available as an executable binary for all platforms, so no ‘installation’ is required as such. Just download and add its location to your Path to access it from anywhere in your terminal.

Creating new site with Hugo

After installing Hugo,

hugo new site <name-of-site>

Choose a Hugo theme

Choose a theme (say PaperMod) from Hugo Themes

Clone the theme’s git repo in themes dir in your new site dir.

config.toml / config.yml

Edit config.toml:

  • set the theme
  • set the title
  • set baseURL ‘https://….’ (e.g. if you want to publish to github, you would use <your-git-username>.github.io)

You may see different themes use different conventions, like some use config.yml instead of toml etc. Best practice is to follow the documentation of the particular theme you are using.

Start the local server

hugo server

starts server locally and it refreshes on every change, while you develop.

Create a new Post

hugo new posts/mypost.md

This will create a new md file under content/posts/ Open the file and you can delete draft or set it to false.

You can now start editing this md file and write your blog post!

Create 2 GitHub repos

  • 1st repo - to store the code (does not store the static site)

  • 2nd repo(static site repo) - to store the static site.

2nd must have atleast 1 commit and should have main branch (commit it from somewhere + push to main, so remote has them, or use inbuilt github when it asked “initialize with readme?”)

Add a git submodule

The submodule will refer to 2nd repo and will exist at the folder public that is inside 1st repo.

git submodule add -b main <url of 2nd> public`

Notice the folder for submodule is specified and is named public here.

giving public failed and had to cd into public because public got created when I ran hugo server For similiar case later, I just deleted the public folder, and retried submodule add.

also the 1st (your blog-code-repo) should be a git repo already, then adding the submodule would work. So better make your hugo-project a git repo first.

This will create a public folder and populate it with 2nd repo.

Adding 2nd repo as submodule makes it possible to directly push generated stuff in 2nd repo (that will effectively deploy the site on GutHub pages)

Build the code

hugo -t <name of theme>`

example hugo -t PaperMod creates static content (say 10 pages, one sitemap etc…) in public dir.

btw if you just check where the origin is pointing to when you are inside the public folder - it will point to the 2nd repo - because you are inside public folder that you created using submodule.

git remote -v

Deploy site to GitHub

Now, cd into the public folder, see the files generated by Hugo, and push them to origin (2nd repo)

cd public
git push origin main

Enable Github Pages in your 2nd repo, and see the site live!

Congrats! you now have a live static-site created using Hugo.

Thanks to adityatelange for the theme PaperMod that is also used to create this blog.