Homepages on Hugo

Note: This post used to contain some code examples, but they needed to be removed due to them not playing nice with nunjucks. I apologize for this.

In keeping with the tradition of this blog being mostly written work about the blog itself by volume, I have a surprise for you today: More written work about the site! If you look at the main pages for the site, anything that doesn't have the blog. prefix in the URL, you won't notice any changes at all, but under the hood there's a fair bit that has been changed.

I started the main pages project as a way to learn to build a site on my own. Thus, I quickly ran into one of the very common web development problems: How do I stop myself from writing everything over and over again? I think my initial intention was good, but I didn't know what would drive me up the wall, so I dove in blind. I'm glad I did because it gave me an appreciation for the tools I use for the blog to such a degree that I wanted to learn more about how to use them.

Let me stop talking around the thing. I've built a new theme for Hugo, the static site generator I use to build the blog. This theme, called WebQuest, is based on the layouts and CSS that I'd built for the main pages of this site. The ones that don't look like the blog. There's an idea of making a DRY project in computer science and web development. It stands for Don't Repeat Yourself. By using a SSG, I can stop repeatedly typing in the same head section on every page. At the same time, I don't want to lose the handmade feel, so I am committing to writing all of the template files myself, with no pre-built theme.

The theme is not ready for public consumption as a hugo module yet, but at the end of it, I would like to have something I can give back to the indie web world. Right now, the theme is sanitized, but very simple and requires a fair bit of bespoke customization for my site. Since the site is pretty simple, the theme components are pretty simple too for now. Let's take a look at some examples.

This is the baseof.html file. This tells Hugo the general structure of a page. You'll see here a few selections inside curly braces. These allow for the dynamic insertion of code from other files. The partials take entire files, while the block takes portions of other templates. Let's look at one of the inserted partials.

Here's the HEAD partial. It mostly looks like the head section of any website. The unusual thing is the curly braced code. These codes tell Hugo to insert specific parameters into the HTML that surrounds it, like the page's {{ .Title }}. The dot in front of the Title keyword here tells Hugo to use the current context. Since we aren't inside any other sections marked by braces, this context is the current page. Other variables, like {{ site.Title }} tell Hugo that the context is different. In this case, it's the entire site's Title, as set in the hugo.yaml file. This head.html file can be used on every page, regardless of which page it is and the page title will update automatically, but it isn't the version I'm using. Let's take a look at that one to see why.

The key differences here between the slightly more public-ready version and mine are small but significant. First thing is you'll notice a $codestyles variable being set. That's for Highlight.js to know how to color code in the pages. The default template also uses Highlight.js, but it's hosted on a CDN. For my site, I want to host the script myself. You can see me call the script at the bottom of the head block. The other thing you'll notice is below the title. This bit of code checks to see if the page's permalink is the Webring permalink. If it is, it includes a separate HTML file that has the webring members array in it, as well as a link to the Webring script.

Now this one is short and sweet. This is single.hmtl, the file Hugo uses when it determines a page's type is that of a single page, rather than a section full of additional pages. Here, all we're doing is defining the "main" block. If you scroll up to the baseof.html file, you'll see where we're calling the main block. Here, we use the context of the current page again, grabbing the title and content. Then, we exit the main block. Nice and easy. With a few more partials here and there, and some overriden local layouts, I've got a feature comparable version of the site as it was last week and it only took me 35 commits.