Hugo Static Site Generator Tutorial

Hugo is a static site generator written in Go. It takes pride in being fast given that it’s written in a language as close to C that you’ll get.


There are far too many platforms for this tutorial to cover you should go here for installation instructions.


Create a new site:

$ hugo new site <mywebsite>
|   archetypes
|   config.toml
|   content
|   data
|   layouts
|   static
|   themes

Run the site on a server:

$ hugo server

Hugo default server

Build the entire site into /public:

$ hugo

Quick rundown

  • You write your blog posts inside of /content in markdown.
  • /layouts are .html files that content is placed into.
  • config.toml stores global hugo configuration options.
  • /static stores static content such as .js, .css, .png.
  • /themes is where you install custom themes using Git.
  • /archetypes adds variables to the content’s font matter and /data stores custom variables for your layouts to use.


Hugo would rather you use a custom theme instead of building one from scratch.

Make sure you’re inside the /themes directory and then head over to

Pick one and git clone it into themes:

$ git clone

Open config.toml and add the theme then run the server:

baseurl = ""
languageCode = "en-us"
title = "My New Hugo Site"
theme = "hugo-cactus-theme"

Hugo Cactus Theme

Hugo by default has liveReload enabled and thus any new files you create or change will reload the browser. Create a blog post:

$ hugo new post/

Hugo first post

Make your own theme

Remove theme from your config.toml file.

Change directory into /layouts and make a directory named post with a single.html file:

<!DOCTYPE html>
  {{ .Content }}

Now open /content/post/ and add the layout type of post:

date = "2016-07-25T21:04:23-05:00"
description = ""
title = "first"
type = "post"


# My first blog post

Hugo Custom Theme Layout

Partials give us the ability to break our layouts into parts such as head, footer, navbar:

# inside of /layouts
$ mkdir partials
$ cd partials
$ touch head.html

Open the newly created head.html:

  <link href="/css/main.css" rel="stylesheet">

Create the main.css file inside of /static/css and add the partial to your post layout:

/* /static/css/main.css */
	background: orange;


<!DOCTYPE html>
<html lang="en">
        {{ partial "head.html" .}} 
        {{ .Content }}

Hugo partials

Where’s the home page?

You would think that it would be inside of /content/ right? Well no it’s not. In fact it’s considered a template /layouts/index.html:

<!DOCTYPE html>
  <h1>Home page</h1>

Hugo homepage

Push it to Github

Open config.toml and add github as the baseurl:

baseurl = "https://<yourusername><yourreponame>"
canonifyurls = true
languageCode = "en-us"
title = "My Website"

Build the site:

$ hugo

Move /public/ to its own directory:

$ mv -v public/* ~/yourgitrepo

Inside of your git repo:

# ~/yourgitrepo
$ git init 
$ git checkout -b gh-pages
$ git add --all
$ git commit -m "commit"

Create a new repo on Github:

Hugo Github Repo

Submit and look for the line …or push an.., but only run the first line:

Hugo Push Repo

Push it and then visit the URL

$ git push origin gh-pages

Hugo Completed Push to Github


From here you should read up on the official Hugo Docs to cover the parts this tutorial missed.