Let’s Build Some Default Layouts
Layouts are a type of template in Hugo. There are several different types of templates which will talk about in later blog posts They include partials, shortcodes, and a lesser known subject called attribute lists. , however, layouts are the most commonly used form.
Interesting enough, layouts are often the most confusing aspect of putting together a site with Hugo. Which is great (not because it is confusing) but because we are going to work through it step by step and eliminate any confusion going forward. Once we’ve covered this topic, probably in way too much detail, it’ll set you up for being able to do some pretty incredible things with Hugo.
The Best Model To Understand
Understanding the model of how layouts, and for that matter templates work, the best reference point is that standard mail merge process used in something like Word or any other word processing program. When you create a mail merge, you start with the template and the template contains the details that will be the same for everyone. There are things like the design of the page, your signature, the return address, etc.
Within the template will be special areas or lines, usually structured with double curly braces, e.g. {{ }}. When the template runs, a process is used to insert content like individual people’s names and addresses into those areas of template marked off by the curly braces. So, if you had something like {{ first_name }} in your template, when your template ran it would be replaced by whatever the first name of a person happened to be.
In Layouts, it is exactly the same thing.
Our Previous Example
Recall from our previous example:
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
<title>my-new-site</title>
</head>
<body>
{{ .Content }}
</body>
</html>
In this case, with Hugo, our content is what is being replaced into the layout and it is right there inbetween the two html <body> tags as {{ .Content }}. This layout tells Hugo to create webpages on our site using the above as a template, and for each page on our site, it inserts the content of that page exactly at the {{ .Content }} entry in the template.
Knowing this we cen expand on our layout and include something really basic like a header or a nav element. Let’s do that now and see what it looks like:
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
<title>my-new-site</title>
</head>
<body>
<header>
<h2>This is the header</h2>
</header>
{{ .Content }}
</body>
</html>
In the above code, we just inserted an html header tag above our content. If your hugo server was still running from the previous exercise you should see that it immediately updates.
On the topic of automatic updates, that is one of the benefits of Hugo, it can regenerate ALL the pages on your site, sometimes in under 10 ms, yup - that’s one of the reasons so many people love Hugo.
Don’t Worry! I know these pages aren’t all too much to look at right now, however, I’m going to walk through how to go from a really basic site to something that looks incredible and you’ll be able to customize it any way you like. However, we need to get through the foundations of how these things all tie together or, when you go to make a change later on you, you’ll be frustrated. Trust me, I was crazy frustrated when I got started with Hugo and part of the reason to put this together is so that you won’t be.
Types of Layouts
Here’s where things start to really get fun. Remember … the hierarchy: there are templates, one kind of template is a layout, and now we’ll review the different kinds of layouts.
When building a website you are going to need more than just one type of template. You might have things like blog posts, and those all follow a similar tempalte, and you might have things like about us and contact pages and each of those might have their own template. All told you could have any number of different types of content on your site and each of those might need to have it’s own layout.
baseof.html - Where It All Starts
Hugo names it’s very base starting point template baseof.html. This is a specific file name that Hugo looks for and you must name your base layout with this naming convention. This template file is usually used exactly the way we have set it up. It contains the base elements of an HTML page such as the <head> and <body> tags.
One easy way I like to think of the baseof.html layout is as a parent layout. Then, in the most common case, it has two children: single.html and list.html.
[TODO - Create Parent / Child Relationship Image here]
Now We Get Complicated: single.html and list.html
And now we start to get complicated. The next two types of layouts are named after the two common types of context in which they are used. In the case of single.html I like to think of this as being used when I’m displaying a single item - kinda like a single post in a blog or a single page like and ‘About Us’ or ‘Contact’ page.
Alternatively, the list.html is used when displaying a list or content elements. These would be most similarl to say a list of blog posts or a list of products, for example.
By themselves, these two layouts don’t seem all too complicated. However, it is complicated understanding how Hugo decides which layout it is going to use. To understand this fully there are several topics that we’ll need to understand and introduce. The first will be content type.
In order to understand the content type, we need to look at the content directory. While we’ll have more to say about how the content directory is structured in future blog posts, I’ve included a sample image here that should be clearer about when the single.html vs. list.html layout is used.
However, this post has gone on for awhile talking about how these different layouts work together. Let’s learn by doing and in the next post we’ll walk through a few examples that help demonstrate how Hugo decides which layout to use.