Develop a Theme for Hugo
This article was originally published on zeolearn .
Introduction
In this tutorial, I will show you how to create a basic Hugo theme. I assume that you are familiar with basic HTML, and how to write content in markdown. I will be explaining the working of Hugo and how it uses Go templating language and how you can use these templates to organize your content. As this post will be focusing mainly on Hugo's working, I will not be covering CSS here.
We will be starting with some necessary information about the terminology used in Hugo. Then we will create a Hugo site with a very basic template. Then we will add new templates and posts to our site as we delve further into Hugo. With very slight variations to what you will learn here, you will be able to create different types of real-world websites.
Now, a short tutorial about the flow of this post. The commands that start with
$
$
are meant to be run in the terminal or command line. The output of the
command will follow immediately. Comments will begin with #
#
.
Some Terminology
Configuration File
Hugo uses a configuration file to identify common settings for your site. It is located in the root of your site. This file can be written in TOML, YAML or JSON formats. Hugo identifies this file using the extension.
By default, Hugo expects to find Markdown files in your content/
content/
directory and
template files in your themes/
themes/
directory. It will create HTML files in your
public/
public/
directory. You can change this by specifying alternate locations in
the configuration file.
Content
The content files will contain the metadata and text about your posts. A content
file can be divided into two sections, the top section being frontmatter and the
next section is the markdown that will be converted to HTML by Hugo. The content
files reside in /content
/content
directory.
Frontmatter
The frontmatter section contains information about your post. It can be written
in JSON, TOML or YAML. Hugo identifies the type of frontmatter used with the
help of identifying tokens(markers). TOML is surrounded by ---
---
, YAML is by
---
---
and JSON is enclosed in curly braces {
{
and }
}
. The information in the
front matter of a content type will be parsed to be used in the template for
that specific content type while converting to HTML.
I prefer to use YAML, so you might need to translate your configurations if you are using JSON or TOML.
This is an example of frontmatter written in YAML.
---
date: "2018-02-11T11:45:05+05:30"
title: "Basic Hugo Theming Tutorial."
description:
"A primer about theme development for Hugo, a static site generator written in
Golang."
categories:
- Hugo
- Customization
tags:
- Theme
---
---
date: "2018-02-11T11:45:05+05:30"
title: "Basic Hugo Theming Tutorial."
description:
"A primer about theme development for Hugo, a static site generator written in
Golang."
categories:
- Hugo
- Customization
tags:
- Theme
---
You can read more about different configuration options available for frontmatter here .
Markdown
The markdown section is where you will write your actual post. The content written here will automatically be converted to HTML by Hugo with the help of a Markdown engine.
Templates
In Hugo, templates govern the way; your content will be rendered to HTML. Each
template provides a consistent layout when rendering the markdown content. The
templates reside in the /layouts
/layouts
directory.
There are three types of templates: single, list and partial. Each kind of template take some content as input and transform it according to the way defined in the template.
Single Template
A single template is used to render a single page. The best example of this is about page.
List Template
A list template renders a group of related content. It can be all recent posts or all posts belonging to a particular category.
The homepage template is a specific type of list template. Hugo assumes that the homepage will serve as a bridge to all the other content on your website.
Partials
Partials are short code snippets that can be injected in any other template type. They are instrumental when you want to repeat some content on every page of your website. The header and footer content are good candidates to be included in separate partials. It is a good practice to use partials liberally in your Hugo site as it adheres to DRY principle.
Okay, Let's Start
So now that you have a basic understanding of Hugo, we will create a new site using Hugo. Hugo provides a command to generate new sites. We will use that command to scaffold our site. It will create a basic skeleton of your site and will give you a basic configuration file.
$ hugo new site ~/zeo
$ cd ~/zeo
$ ls -l
total 28
drwxr-xr-x 2 yash hogwarts 4096 Feb 11 11:13 archetypes
-rw-r--r-- 1 yash hogwarts 82 Feb 11 11:13 config.toml
drwxr-xr-x 2 yash hogwarts 4096 Feb 11 11:13 content
drwxr-xr-x 2 yash hogwarts 4096 Feb 11 11:13 data
drwxr-xr-x 2 yash hogwarts 4096 Feb 11 11:13 layouts
drwxr-xr-x 2 yash hogwarts 4096 Feb 11 11:13 static
drwxr-xr-x 2 yash hogwarts 4096 Feb 11 11:13 themes
$ hugo new site ~/zeo
$ cd ~/zeo
$ ls -l
total 28
drwxr-xr-x 2 yash hogwarts 4096 Feb 11 11:13 archetypes
-rw-r--r-- 1 yash hogwarts 82 Feb 11 11:13 config.toml
drwxr-xr-x 2 yash hogwarts 4096 Feb 11 11:13 content
drwxr-xr-x 2 yash hogwarts 4096 Feb 11 11:13 data
drwxr-xr-x 2 yash hogwarts 4096 Feb 11 11:13 layouts
drwxr-xr-x 2 yash hogwarts 4096 Feb 11 11:13 static
drwxr-xr-x 2 yash hogwarts 4096 Feb 11 11:13 themes
Note: I will use YAML format for the config file. Hugo, By default, uses TOML format.
A small description of this directory structure:
-
archetypes: The archetypes contains predefined frontmatter format for your website's content types. It facilitates consistent metadata format across all the content of your site.
-
content: The content directory contains the markdown files that will be converted to HTML and served to the user.
-
data: From Hugo documentation
The data folder is where you can store additional data for Hugo to use when
generating your site. Data files are not used to generate standalone pages;
rather, they are meant to be supplemental to content files. This feature can
extend the content in case your front matter fields grow out of control. Or
perhaps you want to show a larger dataset in a template (see example below).
In both cases, it is a good idea to outsource the data in their files. -
layouts: The layouts folder stores all the templates files which form the presentation of the content files.
-
static: The static folder will contain all the static assets such as
CSS
CSS
,JS
JS
andimage
image
files. -
themes: The themes folder is where we will be storing our theme.
We will edit the config.yaml
config.yaml
file to edit some basic configuration of the
site.
$ vim config.yaml
baseURL: /
title: "My First Blog"
defaultContentLanguage: en
languages:
en:
lang: en
languageName: English
weight: 1
MetaDataFormat: "yaml"
$ vim config.yaml
baseURL: /
title: "My First Blog"
defaultContentLanguage: en
languages:
en:
lang: en
languageName: English
weight: 1
MetaDataFormat: "yaml"
Now when you run your site, Hugo will show some errors. It is normal because our layouts and themes directories are still empty.
$ hugo --verbose
INFO 2018/02/11 11:20:59 Using config file: /home/yash/zeo/config.yaml
Building sites ... INFO 2018/02/11 11:20:59 syncing static files to /home/yash/zeo/public/
WARN 2018/02/11 11:20:59 No translation bundle found for default language "en"
WARN 2018/02/11 11:20:59 Translation func for language en not found, use default.
WARN 2018/02/11 11:20:59 i18n not initialized, check that you have language file (in i18n) that matches the site language or the default language.
WARN 2018/02/11 11:20:59 [en] Unable to locate layout for "taxonomyTerm":
...
...
$ hugo --verbose
INFO 2018/02/11 11:20:59 Using config file: /home/yash/zeo/config.yaml
Building sites ... INFO 2018/02/11 11:20:59 syncing static files to /home/yash/zeo/public/
WARN 2018/02/11 11:20:59 No translation bundle found for default language "en"
WARN 2018/02/11 11:20:59 Translation func for language en not found, use default.
WARN 2018/02/11 11:20:59 i18n not initialized, check that you have language file (in i18n) that matches the site language or the default language.
WARN 2018/02/11 11:20:59 [en] Unable to locate layout for "taxonomyTerm":
...
...
This command will also create a new directory called public/
public/
. This is the
directory where Hugo will save all the generated HTML files related to your
site. It also stores all static data in this folder.
Let's have a look at the public
public
folder.
$ ls -l public/
total 16
drwxr-xr-x 2 yash hogwarts 4096 Feb 11 11:22 categories
-rw-r--r-- 1 yash hogwarts 400 Feb 11 11:25 index.xml
-rw-r--r-- 1 yash hogwarts 383 Feb 11 11:25 sitemap.xml
drwxr-xr-x 2 yash hogwarts 4096 Feb 11 11:22 tags
$ ls -l public/
total 16
drwxr-xr-x 2 yash hogwarts 4096 Feb 11 11:22 categories
-rw-r--r-- 1 yash hogwarts 400 Feb 11 11:25 index.xml
-rw-r--r-- 1 yash hogwarts 383 Feb 11 11:25 sitemap.xml
drwxr-xr-x 2 yash hogwarts 4096 Feb 11 11:22 tags
Hugo generated some XML files, but there are no HTML files. It is because we have not created any content in our content directory yet.
At this point, you have a working site with you. All that is left is to add some content and a theme to your site.
Create a new theme
Hugo doesn't ship with a default theme. There are a lot of themes available on Hugo website. Hugo also ships with a command to create new themes.
In this tutorial, we will be creating a theme called zeo
zeo
. As mentioned
earlier, my aim is to show you how to use Hugo's features to fill out your HTML
files from the markdown content, I will not be focusing on CSS. So the theme
will be ugly but functional.
Let's create a basic skeleton of the theme. It will create the directory structure of the theme and place empty files for you to fill in.
# run it from the root of your site
$ hugo new theme zeo
$ ls -l themes/zeo/
total 20
drwxr-xr-x 2 yash hogwarts 4096 Feb 11 11:30 archetypes
drwxr-xr-x 4 yash hogwarts 4096 Feb 11 11:30 layouts
-rw-r--r-- 1 yash hogwarts 1081 Feb 11 11:30 LICENSE.md
drwxr-xr-x 4 yash hogwarts 4096 Feb 11 11:30 static
-rw-r--r-- 1 yash hogwarts 432 Feb 11 11:30 theme.toml
# run it from the root of your site
$ hugo new theme zeo
$ ls -l themes/zeo/
total 20
drwxr-xr-x 2 yash hogwarts 4096 Feb 11 11:30 archetypes
drwxr-xr-x 4 yash hogwarts 4096 Feb 11 11:30 layouts
-rw-r--r-- 1 yash hogwarts 1081 Feb 11 11:30 LICENSE.md
drwxr-xr-x 4 yash hogwarts 4096 Feb 11 11:30 static
-rw-r--r-- 1 yash hogwarts 432 Feb 11 11:30 theme.toml
Fill out LICENSE.md
LICENSE.md
and theme.toml
theme.toml
file if you plan to distribute your theme
to outside world.
Now we will edit our config.yaml
config.yaml
file to use this theme.
$ vim config.yaml
theme: "zeo"
$ vim config.yaml
theme: "zeo"
Now that we have an empty theme, let's build the site.
$ hugo --verbose
INFO 2018/02/11 11:34:14 Using config file: /home/yash/zeo/config.yaml
Building sites ... INFO 2018/02/11 11:34:14 syncing static files to /home/yash/zeo/public/
WARN 2018/02/11 11:34:14 No translation bundle found for default language "en"
WARN 2018/02/11 11:34:14 Translation func for language en not found, use default.
WARN 2018/02/11 11:34:14 i18n not initialized, check that you have language file (in i18n) that matches the site language or the default language.
| EN
+------------------+----+
Pages | 3
Paginator pages | 0
Non-page files | 0
Static files | 0
Processed images | 0
Aliases | 0
Sitemaps | 1
Cleaned | 0
Total in 12 ms
$ hugo --verbose
INFO 2018/02/11 11:34:14 Using config file: /home/yash/zeo/config.yaml
Building sites ... INFO 2018/02/11 11:34:14 syncing static files to /home/yash/zeo/public/
WARN 2018/02/11 11:34:14 No translation bundle found for default language "en"
WARN 2018/02/11 11:34:14 Translation func for language en not found, use default.
WARN 2018/02/11 11:34:14 i18n not initialized, check that you have language file (in i18n) that matches the site language or the default language.
| EN
+------------------+----+
Pages | 3
Paginator pages | 0
Non-page files | 0
Static files | 0
Processed images | 0
Aliases | 0
Sitemaps | 1
Cleaned | 0
Total in 12 ms
These warnings are harmless in our case, as we are developing our site in English only.
Hugo does two things while generating your website. It transforms all the content files to HTML using the defined templates, and its copies static files into the site. Static files are not transformed by Hugo. They are copied exactly as they are.
The Cycle
The usual development cycle when developing themes for Hugo is:
- Delete the
/public
/public
folder - Run the built-in web server and open your site in the browser
- Make changes to your theme files
- View your changes in browser
- Repeat step 3
It is necessary to delete the public
public
directory because Hugo does not try to
remove any outdated files from this folder. So the old data might interfere with
your workflow.
It is also a good idea to track changes in your theme with the help of a version control software. I prefer Git for this. You can use others according to your preference.
Run your site in the browser
Hugo has a built-in web server which helps considerably while developing themes for Hugo. It also has a live reload and watch feature which watches for changes in your files and reloads the web page accordingly.
Run it with hugo server
hugo server
command.
Now open http://localhost:1313
http://localhost:1313
in your browser. By default, Hugo will not show
anything, because it cannot find any HTML file in the public directory.
The command to load web server with --watch
--watch
option is:
$ hugo server --watch --verbose
...
...
| EN
+------------------+----+
Pages | 4
Paginator pages | 0
Non-page files | 0
Static files | 0
Processed images | 0
Aliases | 0
Sitemaps | 1
Cleaned | 0
Total in 11 ms
...
...
$ hugo server --watch --verbose
...
...
| EN
+------------------+----+
Pages | 4
Paginator pages | 0
Non-page files | 0
Static files | 0
Processed images | 0
Aliases | 0
Sitemaps | 1
Cleaned | 0
Total in 11 ms
...
...
Update the Home page template
Hugo looks for following directories in theme's /layout
/layout
folder to search for
index.html
index.html
page.
- index.html
- _default/list.html
- _default/single.html
It is always desirable to update the most specific template related to the content type. It is not a hard and fast rule, but a good generalization to follow.
We will first make a static page to see if our index.html
index.html
page is rendered
correctly.
$ vim themes/zeo/layouts/index.html
<!DOCTYPE html>
<html>
<body>
<p>Hello World!</p>
</body>
</html>
$ vim themes/zeo/layouts/index.html
<!DOCTYPE html>
<html>
<body>
<p>Hello World!</p>
</body>
</html>
Build the site and verify the results. You should see Hello World! when you
open http://localhost:1313
http://localhost:1313
.
Building a functional Home Page
Now we will create a home page which will reflect the content of our site every time we build it.
For that, we will first create some new posts. We will display these posts as a list on the home page and on their pages, too.
Hugo has a command for generating skeleton of posts, just like it did for sites and themes.
$ hugo --verbose new post/first.md
INFO 2018/02/11 11:40:58 Using config file: /home/yash/zeo/config.yaml
INFO 2018/02/11 11:40:58 attempting to create "post/first.md" of "post" of ext ".md"
INFO 2018/02/11 11:40:58 curpath: /home/yash/zeo/archetypes/default.md
...
...
/home/yash/zeo/content/post/first.md created
$ hugo --verbose new post/first.md
INFO 2018/02/11 11:40:58 Using config file: /home/yash/zeo/config.yaml
INFO 2018/02/11 11:40:58 attempting to create "post/first.md" of "post" of ext ".md"
INFO 2018/02/11 11:40:58 curpath: /home/yash/zeo/archetypes/default.md
...
...
/home/yash/zeo/content/post/first.md created
The new
new
command uses an archetype to generate the frontmatter for new posts.
When we created our site, hugo created a default archetype in the /archetype
/archetype
folder.
$ cat archetypes/default.md
---
title: "{{ replace .Name "-" " " | title }}"
date: {{ .Date }}
---
$ cat archetypes/default.md
---
title: "{{ replace .Name "-" " " | title }}"
date: {{ .Date }}
---
It is a good idea to create a default archetype in the themes folder also so that users can override the theme's archetype with their archetype whenever they want.
We will create a new archetype for our posts' frontmatter and delete the default
archetype/default.md
archetype/default.md
.
$ rm -rf archetype/default.md
$ vim themes/zeo/archetypes/post.md
---
title: "{{ replace .Name "-" " " | title }}"
date: {{ .Date }}
Description: ""
Tags: []
Categories: []
---
$ rm -rf archetype/default.md
$ vim themes/zeo/archetypes/post.md
---
title: "{{ replace .Name "-" " " | title }}"
date: {{ .Date }}
Description: ""
Tags: []
Categories: []
---
Create one more post in content/post
content/post
directory.
$ hugo --verbose new post/second.md
INFO 2018/02/11 12:13:56 Using config file: /home/yash/zeo/config.yaml
INFO 2018/02/11 12:13:56 attempting to create "post/second.md" of "post" of ext ".md"
INFO 2018/02/11 12:13:56 curpath: /home/yash/zeo/themes/zeo/archetypes/post.md
...
...
/home/yash/zeo/content/post/second.md created
$ hugo --verbose new post/second.md
INFO 2018/02/11 12:13:56 Using config file: /home/yash/zeo/config.yaml
INFO 2018/02/11 12:13:56 attempting to create "post/second.md" of "post" of ext ".md"
INFO 2018/02/11 12:13:56 curpath: /home/yash/zeo/themes/zeo/archetypes/post.md
...
...
/home/yash/zeo/content/post/second.md created
See the difference. Hugo used the theme's archetype for generating the frontmatter this time.
By default, Hugo does not generate posts with an empty content section. So you will need to add some content before you try to build the site.
Let's look at the content/post/first.md
content/post/first.md
file, after adding content to it.
$ cat content/post/first.md
---
title: "First"
date: 2018-02-11T11:35:58+05:30
draft: true
Tags: ["first"]
Categories: ["Hugo"]
---
Hi there. My first Hugo post
$ cat content/post/first.md
---
title: "First"
date: 2018-02-11T11:35:58+05:30
draft: true
Tags: ["first"]
Categories: ["Hugo"]
---
Hi there. My first Hugo post
Now that our posts are ready, we need to create templates to show them in a list on the home page and to show their content on separate pages for each post.
We will first edit the template for the home page that we created previously. We will then modify "single" templates which are used to generate output for a single content file. We also have "list" templates which are used to group similar type of content and render them as a list. The home page will show a list of last ten posts that we have created. Let's update its template to add this logic.
Update your home page to show your content
Now add your template code to themes/zeo/layouts/index.html
themes/zeo/layouts/index.html
.
$ vim themes/zeo/layouts/index.html $ cat !$ cat themes/zeo/layouts/index.html
<!DOCTYPE html>
<html>
<body>
{{ range first 10 .Data.Pages }}
<h1>{{ .Title }}</h1>
{{ end }}
</body>
</html>
$ vim themes/zeo/layouts/index.html $ cat !$ cat themes/zeo/layouts/index.html
<!DOCTYPE html>
<html>
<body>
{{ range first 10 .Data.Pages }}
<h1>{{ .Title }}</h1>
{{ end }}
</body>
</html>
Hugo uses Go Template Engine. This engine scans the templates for commands that
are enclosed between {{
{{
and }}
}}
. In this template, the commands are range
range
,
first
first
, .Data.Pages
.Data.Pages
, .Title
.Title
and end
end
.
The template implies that we are going to get first 10 latest pages from our
content folder and render their title as h1
h1
heading.
range
range
is an iterator function. Hugo treats every HTML file created as a page,
so range
range
will loop through all the pages created. Here we are instructing
range
range
to stop after first ten pages.
The end
end
command signals the end of the range iterator. The engine loops back
to the next iteration as soon as it encounters the end command. Everything
between range and end will be evaluated for each iteration of the loop.
Build the website and see the changes. The homepage now shows our two posts. However, you cannot click on the posts and read their content. Let's change that too.
Linking your posts on Home Page
Let's add a link to the post's page from home page.
$ vim themes/zeo/layouts/index.html
<!DOCTYPE html>
<html>
<body>
{{ range first 10 .Data.Pages }}
<h1>
<a href="{{ .Permalink }}">{{ .Title }}</a>
</h1>
{{ end }}
</body>
</html>
$ vim themes/zeo/layouts/index.html
<!DOCTYPE html>
<html>
<body>
{{ range first 10 .Data.Pages }}
<h1>
<a href="{{ .Permalink }}">{{ .Title }}</a>
</h1>
{{ end }}
</body>
</html>
Build your site and see the result. The titles are now links, but when you click
on them, it takes you to a page which says 404 page not found
404 page not found
. That is
expected because we have not created any template for the single pages where the
content can be rendered. So Hugo could not find any template, and it did not
output any HTML file. We will change that in a minute.
We want to render the posts, which are in content/post
content/post
directory. That means
that their section is post and their type is also post.
Hugo uses section and type information to identify the template file for each
piece of content. It will first look for a template file which matches the
section or type of the content. If it could not find it, then it will use
_default/single.html
_default/single.html
file.
Since we do not have any other content type yet, we will just start by updating
the _default/single.html
_default/single.html
file.
Remember that Hugo will use this file for every content type for which we have not created a template. However, for now, we will accept that cost as we do not have any other content type with us. We will refactor our templates to accommodate more content types, as we add more content.
Update the template file.
$ vim themes/zeo/layouts/_default/single.html
<!DOCTYPE html>
<html>
<head>
<title>{{ .Title }}</title>
</head>
<body>
<h1>{{ .Title }}</h1>
{{ .Content }}
</body>
</html>
$ vim themes/zeo/layouts/_default/single.html
<!DOCTYPE html>
<html>
<head>
<title>{{ .Title }}</title>
</head>
<body>
<h1>{{ .Title }}</h1>
{{ .Content }}
</body>
</html>
Build the site and verify the results. You will see that on clicking on first
first
,
you get the usual result, but clicking on second
second
still produces the
404 page not found
404 page not found
error. It is because Hugo does not generate pages with
empty content. Remember I mentioned it earlier.
Now that we have our home page and posts page ready, we will build a page to
list all the posts, not just the recent ten posts. This page will be accessible
at http://localhost:1313/post
http://localhost:1313/post
. Currently, this page is blank because there is
no template defined for it.
This page will show the listings of all the posts, so the type of this page will
be a list. We will again use the default _default/list.html
_default/list.html
as we do not have
any other content type with us.
Update the list file.
$ vim themes/zeo/layouts/_default/list.html
<!DOCTYPE html>
<html>
<body>
{{ range .Data.Pages }}
<h1><a href="{{ .Permalink }}">{{ .Title }}</a></h1>
{{ end }}
</body>
</html>
$ vim themes/zeo/layouts/_default/list.html
<!DOCTYPE html>
<html>
<body>
{{ range .Data.Pages }}
<h1><a href="{{ .Permalink }}">{{ .Title }}</a></h1>
{{ end }}
</body>
</html>
Add "Date Published" to the posts
It is a standard practice to add the date on which the post was published on the
blog. The front matter of our posts has a variable named date
date
. We will use
that variable to fetch the date. Our posts are using the default single
template, so we will edit that file.
$ vim themes/zeo/layouts/_default/single.html
<!DOCTYPE html>
<html>
<head>
<title>{{ .Title }}</title>
</head>
<body>
<h1>{{ .Title }}</h1>
<h2>{{ .Date.Format "Sun, Feb 11, 2018" }}</h2>
{{ .Content }}
</body>
</html>
$ vim themes/zeo/layouts/_default/single.html
<!DOCTYPE html>
<html>
<head>
<title>{{ .Title }}</title>
</head>
<body>
<h1>{{ .Title }}</h1>
<h2>{{ .Date.Format "Sun, Feb 11, 2018" }}</h2>
{{ .Content }}
</body>
</html>
Adding top-level Pages
Okay, so now that we have our homepage, post-list page and post content pages in place, we will add a new about page at the top level of our blog, not at a sublevel like we did for posts.
Hugo uses the directory structure of the content directory to identify the
structure of the blog. Let's verify that and create a new about
about
page in the
content directory.
$ vim content/about.md
---
title: "about"
description: "about this blog"
date: "2018-02-11"
---
### about me
Hi there, you just reached my blog.
$ vim content/about.md
---
title: "about"
description: "about this blog"
date: "2018-02-11"
---
### about me
Hi there, you just reached my blog.
Let's generate the site and view the results.
$ hugo --verbose
$ ls -l public/
total 36
drwxr-xr-x 2 yash hogwarts 4096 Feb 11 12:43 about
drwxr-xr-x 3 yash hogwarts 4096 Feb 11 12:43 categories
drwxr-xr-x 2 yash hogwarts 4096 Feb 11 11:20 css
-rw-r--r-- 1 yash hogwarts 187 Feb 11 12:43 index.html
-rw-r--r-- 1 yash hogwarts 1183 Feb 11 12:43 index.xml
drwxr-xr-x 2 yash hogwarts 4096 Feb 11 11:20 js
drwxr-xr-x 4 yash hogwarts 4096 Feb 11 12:43 post
-rw-r--r-- 1 yash hogwarts 1139 Feb 11 12:43 sitemap.xml
drwxr-xr-x 3 yash hogwarts 4096 Feb 11 12:43 tags
$ hugo --verbose
$ ls -l public/
total 36
drwxr-xr-x 2 yash hogwarts 4096 Feb 11 12:43 about
drwxr-xr-x 3 yash hogwarts 4096 Feb 11 12:43 categories
drwxr-xr-x 2 yash hogwarts 4096 Feb 11 11:20 css
-rw-r--r-- 1 yash hogwarts 187 Feb 11 12:43 index.html
-rw-r--r-- 1 yash hogwarts 1183 Feb 11 12:43 index.xml
drwxr-xr-x 2 yash hogwarts 4096 Feb 11 11:20 js
drwxr-xr-x 4 yash hogwarts 4096 Feb 11 12:43 post
-rw-r--r-- 1 yash hogwarts 1139 Feb 11 12:43 sitemap.xml
drwxr-xr-x 3 yash hogwarts 4096 Feb 11 12:43 tags
Notice that Hugo created a new directory about
about
. This directory contains only
one file index.html
index.html
. The about page will be rendered from about/index.html
about/index.html
.
If you look carefully, the about
about
page is listed with the posts on the
homepage. It is not desirable, so let's change that first.
$ vim themes/zeo/layouts/index.html
<!DOCTYPE html>
<html>
<body>
<h1>posts</h1>
{{ range first 10 .Data.Pages }} {{ if eq .Type "post"}}
<h2><a href="{{ .Permalink }}">{{ .Title }}</a></h2>
{{ end }} {{ end }}
<h1>pages</h1>
{{ range .Data.Pages }} {{ if eq .Type "page" }}
<h2><a href="{{ .Permalink }}">{{ .Title }}</a></h2>
{{ end }} {{ end }}
</body>
</html>
$ vim themes/zeo/layouts/index.html
<!DOCTYPE html>
<html>
<body>
<h1>posts</h1>
{{ range first 10 .Data.Pages }} {{ if eq .Type "post"}}
<h2><a href="{{ .Permalink }}">{{ .Title }}</a></h2>
{{ end }} {{ end }}
<h1>pages</h1>
{{ range .Data.Pages }} {{ if eq .Type "page" }}
<h2><a href="{{ .Permalink }}">{{ .Title }}</a></h2>
{{ end }} {{ end }}
</body>
</html>
Now build the site and verify the results. The homepage now has two sections, one for posts and other for the pages. Click on the about page. You will see the page for about. Remember, I mentioned that Hugo would use the single template for each page, for which it cannot find a template file. There is still one issue. The about page shows the date also. We do not want to show the date on the about page.
There are a couple of ways to fix this. We can add an if-else statement to detect the type of the content and display date only if it is a post. However, let's use the feature provided by Hugo and create a new template type for the posts. Before we do that, let's learn to use one more template type which is partials.
Partials
In Hugo, partials are used to store the shared piece of code which repeats in
more than one templates. Partials are kept in themes/zeo/layouts/partials
themes/zeo/layouts/partials
directory. Partials can be used to override the themes presentation. End users
can use them to change the default behavior of a theme. It is always a good idea
to use partials as much as possible.
Header and Footer partials
Header and footer of most of the posts and pages will follow a similar pattern. So they form an excellent example to be defined as a partial.
$ vim themes/zeo/layouts/partials/header.html
<!DOCTYPE html>
<html>
<head>
<title>{{ .Title }}</title>
</head>
<body>
$ vim themes/zeo/layouts/partials/footer.html
</body>
</html>
$ vim themes/zeo/layouts/partials/header.html
<!DOCTYPE html>
<html>
<head>
<title>{{ .Title }}</title>
</head>
<body>
$ vim themes/zeo/layouts/partials/footer.html
</body>
</html>
We can call a partial by including this path in the template
{{ partial "header.html" . }}
{{ partial "header.html" . }}
Update the Homepage template
Let's update our homepage template to use these partials.
$ vim themes/zeo/layouts/index.html {{ partial "header.html" . }}
<h1>posts</h1>
{{ range first 10 .Data.Pages }} {{ if eq .Type "post"}}
<h2><a href="{{ .Permalink }}">{{ .Title }}</a></h2>
{{ end }} {{ end }}
<h1>pages</h1>
{{ range .Data.Pages }} {{ if or (eq .Type "page") (eq .Type "about") }}
<h2>
<a href="{{ .Permalink }}"
>{{ .Type }} - {{ .Title }} - {{ .RelPermalink }}</a
>
</h2>
{{ end }} {{ end }} {{ partial "footer.html" . }}
$ vim themes/zeo/layouts/index.html {{ partial "header.html" . }}
<h1>posts</h1>
{{ range first 10 .Data.Pages }} {{ if eq .Type "post"}}
<h2><a href="{{ .Permalink }}">{{ .Title }}</a></h2>
{{ end }} {{ end }}
<h1>pages</h1>
{{ range .Data.Pages }} {{ if or (eq .Type "page") (eq .Type "about") }}
<h2>
<a href="{{ .Permalink }}"
>{{ .Type }} - {{ .Title }} - {{ .RelPermalink }}</a
>
</h2>
{{ end }} {{ end }} {{ partial "footer.html" . }}
Update the single template
$ vim themes/zeo/layouts/_default/single.html {{ partial "header.html" . }}
<h1>{{ .Title }}</h1>
<h2>{{ .Date.Format "Sun, Feb 11, 2018" }}</h2>
{{ .Content }} {{ partial "footer.html" . }}
$ vim themes/zeo/layouts/_default/single.html {{ partial "header.html" . }}
<h1>{{ .Title }}</h1>
<h2>{{ .Date.Format "Sun, Feb 11, 2018" }}</h2>
{{ .Content }} {{ partial "footer.html" . }}
Build the website and verify the results. The title on the posts and the about page should both reflect the value from the markdown file.
Fixing the date shown on About page
Remember, we had the issue that the date was showing on the about page also. We discussed one method to solve this issue. Now I will discuss a more hugoic way of solving this issue.
We will create a new section template to fix this issue.
$ mkdir themes/zeo/layouts/post $ vim themes/zeo/layouts/post/single.html {{
partial "header.html" . }}
<h1>{{ .Title }}</h1>
<h2>{{ .Date.Format "Mon, Jan 2, 2006" }}</h2>
{{ .Content }} {{ partial "footer.html" . }} $ vim
themes/zeo/layouts/_default/single.html
<!DOCTYPE html>
<html>
<head>
<title>{{ .Title }}</title>
</head>
<body>
<h1>{{ .Title }}</h1>
{{ .Content }}
</body>
</html>
$ mkdir themes/zeo/layouts/post $ vim themes/zeo/layouts/post/single.html {{
partial "header.html" . }}
<h1>{{ .Title }}</h1>
<h2>{{ .Date.Format "Mon, Jan 2, 2006" }}</h2>
{{ .Content }} {{ partial "footer.html" . }} $ vim
themes/zeo/layouts/_default/single.html
<!DOCTYPE html>
<html>
<head>
<title>{{ .Title }}</title>
</head>
<body>
<h1>{{ .Title }}</h1>
{{ .Content }}
</body>
</html>
Note that we have changed the default single template and added that logic in post's single template.
Build the website and verify the results. The about page does not show the
date now, but the posts page still show the date. We can also move the list
template's logic to the index.html
index.html
file of post section template.
Conclusion
We have learnt, how Hugo harnesses the powerful yet simple Go template engine to create the static site generator. We also learnt about partials and their excellent utilization by Hugo in the spirit of Don't Repeat Yourself principle. Now that you know how to make themes in Hugo, go ahead and start creating new beautiful themes. Best of luck for your endaevour.