Build Websites with Hugo

Fast Web Development with Markdown

by Brian P. Hogan

Early praise for Build Websites with Hugo

Acknowledgments

First off, this book wouldn’t be possible without Hugo itself, which is a result of the fantasic work of the Hugo team. Thank you Bjørn Erik Pedersen, Steve Francia, and all of the other amazing people who’ve contributed to Hugo. Thanks to your work, making things on the web is fun again, and I’m excited to share the joy that Hugo brings to everyone who reads this book.

Thank you Tammy Coron for editing this book and keeping me on track. And for asking some pretty great questions when I failed to explain some things.

Thank you Andy Hunt for publishing this book.

Thank you Dan Kacenjar, Greg Myers, Ryan Palo, Aleem Samiullah, Dan Sarauer, Kieran Tully, and Stephen Wolff, for reviewing the draft of this book and catching errors before the general public would have. I wrote this book in chunks, and many pieces got moved around. Your keen eyes caught many places where inconsistencies crept in. Without your help, readers would have gotten confused or stuck in more than a few places.

Thank you to my business associates Mitch Bullard, Jeff Carley, Kevin Gisi, Alex Henry, Jeff Holland, Chris Johnson, Jon Kinney, Nick LaMuro, Myles Steinhauser, Jessica Stodola, Charley Stran, Josh Swan, Erich Tesky, Mitchell Volk, Chris Warren, Mike Weber, and Andrew Vahey for your continued support.

Thank you Lisa and Ana for inspiring me. Thank you Carissa, for your love and support, and for all you do for our family.

Preface

Are you using a database to serve content that rarely changes? If you’re using WordPress, Ghost, or other solutions for your content site, you probably are. Or at best, you’ve set up caching strategies to speed things up and reduce database calls.

Database-driven content management systems like WordPress let you define a common theme shared across your site, making it a breeze to publish new content. However, since most content doesn’t change in real time, you’re sacrificing speed and scalability for features that benefit content creators and developers instead of the people who want to read your content. And that additional complexity means you need more resources in production too: more servers to handle the traffic, standby database servers, a caching layer you have to manage, and more.

There’s no better way to make a snappy content site than by serving static pages from a traditional web server or a content delivery network (CDN). But you don’t have to give up the rapid development features you’ve come to expect. Static site generators, like Hugo,^[1] give you a fantastic middle ground. You get the theming and content management features of a database-driven site without the bloat, security vulnerabilities, or complexities associated with caching.

Hugo gives you a framework for building a fast, organized content site using many of the skills you already have. You define your layouts in HTML and your content in Markdown. Hugo has built-in support for tagging, categorization, related content, multiple output formats, image optimization, and asset handling. While you’re developing your site, Hugo gives you a web server for testing, and automatically refreshes your pages as you change them. When you’re done building your site, Hugo generates a static site that you can upload to your web server.

There are other static website generators available, like Jekyll^[2] and Gatsby,^[3] two popular and well-known choices. Hugo has a few benefits over those other choices. First, Hugo uses a single binary with no dependencies, which means you don’t need a complex build chain or additional runtimes like Node or Ruby to get started or use its features. Unlike Jekyll, Hugo doesn’t assume you’re creating a blog. And unlike Gatsby, you don’t need to learn React to build your themes or content; if you already know HTML and Markdown, you can be productive right away. Finally, Hugo is incredibly fast when it comes to building the site. It can generate thousands of pages quickly, which comes in handy if you’re using Hugo to build something like a documentation website.

In this book, you’ll use Hugo to build a personal portfolio site that you can use to showcase your skills and thoughts to the world. You’ll build the basic skeleton, develop a custom theme, and use content templates to generate new pages quickly. You’ll use internal and external data sources to embed content into your site, and render some of your content in JSON and RSS. You’ll add a blog section with posts and integrate Disqus with your site, and then make your site searchable. While this isn’t a web design book, you’ll integrate modern CSS into the site, and use Hugo’s asset management features to process styles, images, and scripts. Then you’ll integrate Hugo with Node.js and Webpack for those situations where you need a little more flexibility. Finally, you’ll explore deployment with Netlify,^[4] cloud storage, and traditional web hosts so you can share your work with the world.

What’s in This Book

Each chapter of the book covers a specific part of the development process with Hugo.

In Chapter 1, ​Kicking the Tires​, you’ll build the home page and a few supporting pages, along with a skeleton layout.

Then, in Chapter 2, ​Building a Basic Theme​, you’ll transform the layout into a custom theme for the site. You’ll break things up into reusable pieces and put everything in its place.

In Chapter 3, ​Adding Content Sections​, you’ll create the projects section of the site. You’ll work with custom content types and build out more customized layouts for your new content type.

Then, you’ll integrate data into the site in Chapter 4, ​Working with Data​. You’ll leverage front matter from your docs, data from external files, and data from external sites. You will also render some of your content as JSON data.

In Chapter 5, ​Adding a Blog​, you’ll use what you’ve learned so far to use Hugo to build a static blog. You’ll create a content template for blog posts, create a custom layout to control how your posts display, and add support for commenting. You’ll generate lists of posts, including a main list of posts in reverse chronological order, as well as lists for tags and categories.

In Chapter 6, ​Adding Search to Your Site​, you’ll get search working with your site using a search index along with some client-side JavaScript.

Next, in Chapter 7, ​Managing Assets with Pipes​, you’ll set up a proper asset pipeline so that you can manage your JavaScript and CSS files more easily. You’ll switch to using Sass for your stylesheets and explore some of Hugo’s built-in features for handling images. You’ll also look at integrating Webpack with Hugo, and using npm to manage tasks that make building your site easier.

In Chapter 8, ​Deploying the Site​, you’ll explore a few methods to move your site to production for the world to see. You’ll deploy to Netlify, then look at deploying to Amazon S3, and finally, how to deploy to more traditional web servers.

Finally, you’ll find Appendix 1, ​Migrating to Hugo​, which explores the process of what it takes to move an existing site to Hugo.

At the end of each chapter, you’ll find a few additional exercises that will help cement your knowledge of the concepts.

What You Need

You’ll need your trusty text editor and some experience building things for the web with HTML and CSS. This book doesn’t go into much detail about those things and assumes you’ve built websites before. You won’t use any CSS frameworks for the layout of your site, but you will use a small amount of modern CSS. The CSS you’ll use in this book is intended to demonstrate concepts, not to substitute for careful and professional design. However, if you’re an experienced web developer, you’ll be able to see exactly where you can apply your existing knowledge as you build out your design.

Hugo runs on Windows, macOS, and various flavors of Linux and BSD operating systems, and it’s a single binary file with no dependencies. You’ll download and install Hugo in the first chapter. The examples of this book use Hugo version 0.68.3.

Because Hugo is a command-line tool, you should be comfortable using the command-line interface (CLI). You’ll use the hugo command throughout the book to build your site, launch a development server, and generate files. If you want to get more comfortable with the CLI, you’ll find Small, Sharp Software Tools [Hog19] helpful.

The examples in this book will show CLI commands for copying and moving files. These commands will work in the macOS and Linux terminals, and they will also work on Windows machines using the Windows Subsystem for Linux if you’ve configured that. Alternatively, you can use your graphical environment or text editor to manage and create files.

Additionally, some experience with JavaScript will be helpful when integrating search into the site.

Finally, in Chapter 5, ​Adding a Blog​ and Chapter 7, ​Managing Assets with Pipes​, you’ll use Node.js^[5] for some additional tooling. You should have Node.js installed on your system by following the official installation instructions for your platform.

Conventions

Throughout the book you’ll see commands like this:

This is a command that you’ll type at your command-line interface. The dollar sign indicates the prompt. You won’t type that character.

You’ll also see code listings, like this:

Sometimes, you’ll see highlighted sections when adding new lines of code, like this:

You’ll find instructions on where to add the code to your project with each listing, along with details on what the code does.

Online Resources

The book’s website^[6] has links to submit errata for the book as well as the source code for the sites you’ll build in this book. The downloadable source code is there as a reference and contains the site as it exists at the end of each chapter.

Chapter 1
Kicking the Tires

The best way to get comfortable with Hugo is to start building something with it. Throughout this book, you’ll use Hugo to build a portfolio site with a blog. In this chapter, you’ll develop a basic understanding of Hugo, layouts, content, and configuration, which form the foundation for working with Hugo as you build a basic site.

But first, you need to install Hugo.

Installing Hugo

Hugo is available as a single binary. You can install Hugo two ways: using a package manager, or by downloading the binary manually and placing it in a global location so you can run it anywhere.

Hugo comes in two versions: a regular version and an extended version that has additional support for asset management, which you’ll want in Chapter 7, ​Managing Assets with Pipes​.

Package managers are utilities that let you install and remove programs and utilities. Linux systems often have a built-in package manager. If you’re running macOS, you can install the Homebrew^[7] package manager. If you’re using Windows, you can install Chocolatey.^[8] Finally, Linux users can install Linuxbrew,^[9] a version of Homebrew for Linux that offers more up-to-date packages than the package manager that comes with their system.

Installation via a package manager is the easiest method, although you might not always get the most recent version.

If you’re using a Mac and you have Homebrew installed, you can install the extended version of Hugo with:

On Windows, if you have Chocolatey installed, you can install Hugo with this command:

To install Hugo manually, find the extended version’s binary for your operating system on the Releases page^[10] on GitHub. For example, if you’re on Windows, you’re looking for a filename like hugo-extended-x.y.z-Windows-64bit.zip. Download the file.

Now that you’ve manually downloaded the file, you’ll want to add it to your PATH environment variable, which your command-line interface uses to determine where it can find executable programs. That way you can execute it without specifying the full directory location.

On macOS or Linux, copy the executable to /usr/local/bin, which is already included in your PATH environment variable by default.

On Windows 10, create the directory C:\hugo\bin. Copy the hugo.exe file you extracted to C:\hugo\bin, and then add that folder to your PATH environment variable. To do this, use the Windows Search and type “environment”. Choose the option for Edit Environment Variables for My Account. On the screen that appears, press the Environment Variables button, locate PATH in the System Variables section, and press the Edit button. Add c:\hugo\bin. Press OK to save the settings, and then press OK on the rest of the dialogs to close them.

Once Hugo is installed, run the hugo version command from your command-line interface to ensure that Hugo is available in any directory on your system, and that you’ve installed the extended version:

The hugo command has several subcommands that you’ll use as you build your site. You can see a list of all commands with hugo help.

Hugo is installed and ready. Let’s use it to build a basic site.

Creating Your Site

Hugo has a built-in command that generates a website project for you; this includes all of the files and directories you need to get started.

Execute the following command to tell Hugo to create a new site named portfolio:

This creates the portfolio directory, with the following files and directories within:

Each of these directories has a specific purpose:

• The archetypes directory is where you place Markdown templates for various types of content. An “archetype” is an original model or pattern that you use as the basis for other things of the same type. Hugo uses the files in the archetypes folder as models when it generates new content pages. There’s a default one that places a title and date in the file and sets the draft status to true. You’ll create new ones later.

• The config.toml file holds configuration variables for your site that Hugo uses internally when constructing your pages, but you can also use values from this file in your themes. For example, you’ll find the site’s title in this file, and you can use that in your layout.

• The content directory holds all of the content for your site. You can organize your content in subdirectories like posts, projects, and videos. Each directory would then contain a collection of Markdown or HTML documents.

• The data directory holds data files in YAML, JSON, or TOML. You can load these data files and extract their data to populate lists or other aspects of your site.

• The layouts folder is where you define your site’s look and feel.

• The static directory holds your CSS, JavaScript files, images, and any other assets that aren’t generated by Hugo.

• The themes directory holds any themes you download or create. You can use the layouts folder to override or extend a theme you’ve downloaded.

In your terminal, switch to the newly created portfolio directory:

Take a look at the site’s configuration file. Open the config.toml file in your text editor. You’ll see the following text:

This file is written in TOML,^[11] a configuration format designed to be easy to read and modify. The default configuration file only has a handful of data, but you’ll add more as you build out your site.

Hugo’s internal functions use the baseURL value to build absolute URLs. If you have a domain name for your site, you should change this value to reflect that domain. In this book, you’ll use relative URLs, so you can leave this value alone until you’re ready to deploy your site to production.

The title value is where you’ll store the site’s title. You’ll use this value in your layouts, so change it from its default value:

Save the file and exit the editor. You’re ready to start working on the site itself.

Building the Home Page

A typical web page has a skeleton that looks like this:

Every time you create a page, you start with a skeleton such as this and then fill in the body section. Your site will likely have a lot more common elements like navigation, a banner, and a footer. As you build out your site, you end up duplicating all of this content on every page, which is difficult to manage if you do it by hand. That’s why dynamic sites are so popular; they provide mechanisms to reduce duplication by separating the content from the layout.

In a Hugo site, you define layouts that contain this skeleton, so you can keep this boilerplate code in a central location. Your content pages contain only the content, and Hugo applies a layout based on the type of content.

Hugo needs a layout for the home page of your site, a layout for other content pages, and a layout that shows a list of pages, like an archive index or a product list. The following figure illustrates this relationship:

As you can see in the figure, the “home page” of the site has its own layout. The “Product list” page has a “list layout” associated with it. However, the two product pages and the “About” page all share a layout.

In this chapter, you’ll create a layout for the home page and another layout for single pages, and they’ll have nearly identical content. You’ll build a layout for list pages in the next chapter.

Let’s start with the home page layout. Hugo uses a separate layout for the home page because it assumes you’ll want your home page to have a different look than other content pages. For example, your home page might contain a list of recent blog posts or articles, or show previews of other content. Or it might have a larger banner image than other pages. For now, you’ll keep the home page simple.

Create the file layouts/index.html and add the following code, which defines an HTML skeleton for the home page:

To pull in data and content, Hugo uses Go’s http/templates library^[12] in its layouts. While you don’t need a deep understanding of how the templating language works, it’s worth exploring when you want to build more complex templates.

In addition to the HTML code, there are some spots between double curly braces. This is how you define where content goes, and the content can come from many places. The {{ .Site.Title }} lines pull the title field out of the config.toml file you just edited and place it into the <title> and <h1> tags. The .Site prefix tells Hugo to get the value from the site’s data rather than from the page’s data. As you’ll see shortly, pages have their own data that you can use.

The {{ .Content }} line displays the content for the page, which will come from an associated Markdown document in your site’s content folder. Note that this doesn’t use the .Site prefix, because this data is related to the page. When you’re working with a Hugo layout, there’s a “scope”, or “context” that contains the data you want to access. The current context in a template is represented by the dot. In a Hugo layout, the context is set to the Page context, which looks something like this:

For convenience, Hugo makes all of the site’s data available in the Page context under the Site key. That’s why you can do .Site.Title to get the site’s title. To get the page title, you’d use .Title. There are many more pieces of data available to you within this context, and you’ll use many of them later in the book.

You’ve added the {{ .Content }} statement to the home page layout, but you’re probably wondering where the content comes from. For the site’s home page, Hugo will look for the content in a file named _index.md in the content directory. This special filename is how Hugo finds content for all index pages, like the home page and lists of content like tags, categories, or other collections you’ll create.

Create the content/_index.md file and open it in your editor. You can place any valid Markdown content into this file. For this example, add a couple sentences and a list of what’s on the site:

After you’ve added your content, save the file.

Time to test things out. Hugo has a built-in development server that you can use to preview your site while you build it. Run the following command to start the server:

Hugo builds your site and displays the following output in your console letting you know that the server is running:

Visit http://localhost:1313 in your web browser and you’ll see your home page:

Use your browser’s View Source feature and you’ll see the layout and your content combined:

Hugo’s development server automatically reloads files when they change. Open the content/_index.md file in your text editor and make some changes to the content. When you save the file, the changes appear in your browser automatically. There’s no need to install a separate server or browser extension. The single Hugo binary handles it all for you by injecting a little bit of JavaScript at the bottom of each page which handles reloading the page.

In your terminal, press CTRL+C to stop the Hugo server. You’re ready to add another page to the site, but this time you will do it with Hugo’s content generator.

Creating Content Using Archetypes

When you created content/_index.md, you created the file manually. You can tell Hugo to create content pages that contain placeholder content. This way, you never have to start with a blank slate when creating content. Hugo uses archetypes to define this default content.

The file archetypes/default.md—which was generated when you ran the hugo new site command—contains the following code:

This is a Markdown file with YAML front matter and a little bit of templating code that will generate the title from the filename you specify, and fill in the date the file is generated. Hugo uses the front matter of each file when it generates pages. You’ll dig into front matter a lot more in ​Populating Page Content Using Data in Front Matter​. Front matter isn’t required in either content pages or archetypes, but you’ll find it useful in many places as you build out your site. In this case, there’s a draft field set to true. When Hugo generates pages, it will skip pages marked as drafts.

The hugo new command uses this file as a template to create a new Markdown file. Try it out. Create a new “About” page with this command:

This generates the file content/about.md. Open the file in your editor, and you’ll see this code:

The title is filled in, and the front matter also includes the date and time the file was created. It also has a draft status of true. Modify the draft status to false or remove the line entirely so that Hugo will generate this page. Then, below the front matter, add some additional content. When you’re done, your file will look like this:

In order for Hugo to generate this page, you need another layout file. Remember that the layout you created, index.html, is only for the home page of the site. The “About” page you just created is an example of what Hugo calls a “single” page. As such, you need a “single page” layout to display it.

You can create different single page layouts for each content type. These get stored in subdirectories of the layouts directory. You’re not going to do anything that complex yet. To create a default single page layout that every content page will use, store it in the layouts/_default directory. Create that directory now, either in your text editor or on the command line like this:

Now, create the file layouts/_default/single.html by copying the existing layouts/index.html file. Again, you can do this in your editor or the CLI:

Let’s make a slight modification to this file; you’ll have it display the page title in addition to the content. Open the single.html file in your editor and add the title like this:

Save the file and exit the editor. Then, start up the development server again:

Visit http://localhost:1313/about and you’ll see your new page:

The site title, page title, and page content are all visible. The page title comes from the about.md file’s front matter, while the site title comes from the config.toml file. This is a small example of how you can use data from various locations to build your pages.

Stop the Hugo server with CTRL+C. Let’s explore what Hugo creates for you and look at a few options to control it.

Building and Exploring Hugo’s Output

When you run hugo server, it generates your content in memory. To write Hugo’s output to disk, run the hugo command with no options, like this:

This generates the pages for your site in a new directory named public. If you look at that directory’s contents, you’ll see these files and directories:

Hugo has created the HTML files for your home page and the About page, as well as the file index.xml, which is an RSS feed for your site. It’s also created a sitemap file, as well as RSS feeds for your site’s tags and categories. You’re not doing anything with those right now, so you can ignore them.

This public folder is your entire static site. To host it, you could upload the contents of the public folder to your web server, or upload it to your CDN. You’ll explore how to put your site live in Chapter 8, ​Deploying the Site​.

Hugo doesn’t clean up the public folder. If you were to remove some pages or rename them, you would need to delete the generated versions from the public folder as well. It’s much easier to delete the entire public folder whenever you generate the site:

Alternatively, use Hugo’s --cleanDestinationDir argument:

You can tell Hugo to minify the files it generates. This process removes whitespace characters, resulting in smaller file sizes that will make the site download faster for your visitors. To do this, use the --minify option:

The public/index.html now looks something like this:

All the indentation and line breaks are removed. As a result, this file contains fewer bytes, which means it’ll transfer faster when you eventually deploy the files to production.

Your Turn

Before moving on, try the following things to make sure you understand how page creation and content generation works:

1. Change the draft status of the About page’s content back to true and regenerate the site with the hugo command, with no additional options. Notice that the about/index.html file still exists. Use the --cleanDestinationDir option and the about/index.html file will disappear. Set the draft status back to false again and rebuild the site to restore the file.

2. Create a “Résumé” page using hugo new resume.md. The generated title in the front matter will say “Resume”. Open the content/resume.md file in your editor, update the generated title from “Resume” to “Résumé”, and set the draft status to false. Fill in some content, and then run the development web server. Navigate to http://localhost:1313/resume to view the page. The single page content template you created applies to this page as well.

3. Experiment with the default archetype. Change the draft state to false in the default archetype and generate a fourth page called contact.md. This new page will now have the draft state set to false. All future pages you create with the hugo new command will now have this status set.

Wrapping Up

You built a basic Hugo site, and you created a handful of content pages using Hugo’s command-line interface. You’ve also defined the layout those content pages will use. However, you’ve got some duplicate code in your layout, which makes your site more difficult to maintain. In the next chapter, you’ll extract your layout into a reusable theme and organize the code to reduce duplication.

Chapter 2
Building a Basic Theme

You’ve built your site, but you have two nearly identical layout files with a lot of duplicate code. Your site’s layout is going to get more complex as you introduce additional content types, navigation, and styles, so it’s time to start organizing things. So far, you’ve placed all of your layout files into your Hugo site’s layouts directory, but Hugo has another mechanism for controlling how things look: themes.

There are many Hugo themes available that you can use, but instead of using one created by someone else, you’re going to build your own. Many off-the-shelf themes are fairly complex with lots of features that take time to configure properly. It’s best to understand how theming works before you dive into someone else’s code.

A basic Hugo theme only needs these files:

This should look pretty familiar to you from the previous chapter. The index.html file is the home page of the site. The _default directory contains the default layouts applied to single content pages (single.html) and pages that display lists of content pages (list.html). However, as you’ll discover in this chapter, there are some additional files you can create that will let you share code between files.

Let’s get started with your theme.

Generating the Theme

You can make a theme by creating a new directory in the themes folder of your site, but Hugo has a built-in theme generator that creates everything you need for your theme. Execute this command from the root of your Hugo site to generate a new theme named basic:

This command creates the themes/basic directory and several subdirectories and files:

The theme has a place for its own archetypes, as well as directories to store the layout files and static assets like stylesheets, scripts, and images. Each theme has a license file so you can open source your theme if you choose, as well as a configuration file where you can store theme-specific configuration values.

Notice that there’s already a layouts/_default directory with files for single page layouts and list page layouts. There’s also a layouts/index.html file that serves as the home page layout. Those files don’t have any content in them, though.

Move your existing layout files into this new theme. Move the layouts/index.html file to themes/basic/layouts/index.html, and then move layouts/_default/single.html to themes/basic/layouts/_default/single.html. You can do this quickly with these commands:

Before you can use the theme, you have to tell Hugo about it by adding a line to your site’s configuration. Open config.toml and add the following line to the end:

Save the file and run the server again:

Visit http://localhost:1313 in your browser. Your home page still displays, which means your theme works. Once you know it works, stop the development server with Ctrl-c.

Now, let’s break the theme up and reduce some duplication by taking advantage of Hugo’s layout framework.

Using Content Blocks and Partials

Your home page layout and single page layout both contain the HTML skeleton. That skeleton is going to get a lot more complex once you add a header, footer, and navigation. Instead of duplicating that code in multiple places, Hugo provides a single place for you to put your skeleton so that all other layouts can build on it. When you created the theme, it generated it for you.

Locate the file themes/basic/layouts/_default/baseof.html and open it in your editor. You’ll see this code:

This file will be the “base” of every other layout you’ll create, hence its name. And instead of including the full skeleton, it’s pulling in other files, or partials, which contain pieces of the layout. Placing common pieces in partials makes it easier for you to reuse these across different layouts, and it helps you think about parts of your site as components. The template generator also created these files, but it left them blank. Let’s fill them in, one piece at a time.

The first partial listed in the baseof.html file is the head.html file, which you’ll find in themes/basic/layouts/partials/head.html. This file will contain the code that would normally appear in the head section of a website. Open it in your editor.

Add the following code to the file to define the head element, with one meta tag that specifies the content type, another meta tag that specifies the viewport, so your page will scale properly on mobile devices, and finally, the title of the site:

Save the file when you’ve made those changes.

The next partial reference is the header.html file, so open the file themes/basic/layouts/partials/header.html. This file will hold the header of your page. It’s where you’ll put the banner and navigation. Add the following code to add an HTML header section and a nav section with links to the root of the site and the static pages you created in the previous chapter:

Hugo has support for a more complex menu system, where you can configure your menu titles and destinations in your site’s configuration file, but for small sites like this, it’s less work to hard-code the URLs in the navigation. Since the navigation is in a partial, you only have to maintain it in a single file, so there’s no advantage to doing it in a data-driven fashion like you would with a dynamic site.

Finally, create the footer of the site by opening themes/basic/layouts/_default/partials/footer.html, the last partial referenced in the baseof.html file. Add a footer element and a copyright date to the file with the following code:

You’re using Go’s date formatting to print out the current year. Go uses Mon Jan 2 15:04:05 MST 2006 as a reference time for its formatters. Instead of having to use special characters to parse out a current time, Go lets you use this reference time to format the specific dates and times. In this case, you only want the year, so you can use “2006” as the formatting string.

All of the partials for the base template are in place, but before moving on, let’s look at the syntax for partials in the baseof.html file. Partials in the baseof.html template that Hugo generated for you look like this:

Previously, when you’ve used those curly braces to inject the title, you used {{. But this code uses {{-. The dash suppresses whitespace characters in the output, such as spaces and newline characters. Placing a dash after the opening braces removes all whitespace in front of the expression, and placing the dash in front of the closing braces removes whitespace after the expression. In most cases, it’s up to you whether or not you want to use them, but you’ll often see dashes used to reduce the number of blank lines in the files Hugo generates.

In addition to the dashes, there’s a dot after the name of the partial. The partial function takes a filename and a context for the data. In order to access data like the page title and content, you have to pass the context to the partial function, and a period means “the current context.” Remember that the default context for a layout is the Page context, so when you pass the dot to the partial function, you’re making the Page context available to the partial.

To use the new base template, replace the existing layouts you’ve used with code that defines a layout “block”. In the baseof.html file, you’ll find this line:

This line looks for a block named “main” and pulls it in. Those blocks are what you’ll define in your actual layout pages like index.html and single.html. Notice it’s also passing the current context, so you’ll be able to access it in the layout pages.

Define this block in your home page layout first. Open themes/basic/layouts/index.html and replace the contents with this code, which defines the main block:

When Hugo builds the site, it’ll construct the home page by combining the content file (content/_index.md) with the layout file, which will then use the baseof file. The partials and content are all assembled, creating the full page.

The index.html layout only affects your site’s home page, so modify the code in themes/basic/layouts/_default/single.html so the single page layout works the same way:

This code looks just like the code in the home page layout, except you’re also displaying the title of the page.

With the changes in place, make sure all your files are saved and then fire up the development server with hugo server. Visit http://localhost:1313 and test your pages. The home page displays with the current year displayed in the footer.

Use the navbar you created to jump between pages to ensure they all work.

You now have a working theme that’s organized and maintainable. Let’s add some CSS to make it look nice.

Styling the Theme with CSS

In addition to layout files, themes contain images, scripts, and the stylesheets that control the visual aspects of the site, such as colors, fonts, and placement of content. These assets go in the static/ directory of your theme. You’ll find both a css folder and js folder in your theme’s static folder.

To style your site, you could bring in any number of CSS frameworks, but for this site, you’ll build a very bare-bones layout by hand using plain CSS. Modern browsers have built-in support for newer CSS features like Flexbox^[13] or CSS Grid, which makes it much less challenging to build a layout.

The theme you’re going to build in this book won’t win any design awards, but it will give you a place to start from and show you how to integrate CSS into your Hugo site.

Before diving into the CSS, let’s add more structure to the layout so you can have more control over the width of the page. This will be helpful on larger devices. Modify the baseof file to wrap everything in a div with the class of container, and change the existing div tag around the main block to an HTML main sectioning tag. The main tag will make it easier for assistive technology to identify the site’s main content, and the container div will let you control how wide the site is on larger monitors when you add the CSS:

Save the file.

Now, create the stylesheet itself. Since you’re making a theme, create the file themes/basic/static/css/style.css.

In the file, add this code to define the width of the container:

Next, define the background and foreground colors for the navigation bar and footer of the site, and center the text in both:

On small screens, the navigation elements will need to stack as a list; on larger screens, the navigation can be a long horizontal navigation bar. Add this code to style the navbar for both small and large screens:

This code defines the nav element as a Flexbox region and defines the elements in the region to flow as a column. It then sets the anchor elements within the navbar as flex elements, evenly spaced apart. After that, it defines a color for each element and centers the text for each link. From there, using a media query targeting on larger screens, it redefines the flex-direction to align the contents as a row.

Finally, in the head.html partial, add a link tag to load a stylesheet named style.css, which will be located in the css directory:

The relURL function creates site-root-relative link to the file instead of an absolute link that contains the site’s domain name. For ease of development and deployment, you should use relative URLs whenever possible. When Hugo generates the site, it’ll copy the contents of the themes/basic/static directory, including all subdirectories, into the public directory, so your CSS file will be located at /css/style.css.

Save the file and switch back to your browser. The styles are applied to the page and you have a basic theme. In Chapter 7, ​Managing Assets with Pipes​, you’ll explore more things you can do with CSS.

In this chapter, you kept the stylesheet in the static directory of the theme instead of in the static directory in your Hugo site. It’s best to follow this convention and use your site’s static directory for images or other assets that are specific to your site, and keep things that are specific to the theme within the theme’s directory structure. When you generate your site, Hugo will grab files from both places and put them in the public directory. If you name files the same, the ones in your site’s static directory will override the ones in the theme.

Your Turn

To solidify your understanding of how theming works in Hugo, try the following exercises:

1. Currently, the header partial contains the site’s header and navigation. Use what you’ve learned about partials to move the navigation section into its own partial called nav.html.

2. Create a new theme named “bootstrap” using the theme generator. Create a layout using Bootstrap instead of your own custom CSS. Follow Bootstrap’s documentation^[14] to create your theme. To test it out, be sure to switch your site’s theme in config.toml. Be sure to switch the theme back to basic before continuing on with the book.

3. Look at the Hugo theme gallery^[15] and examine the source code for an existing theme you like. If you have Git installed, use Git to download the theme to your site and try it out. Many public themes have additional settings you’ll have to configure, so explore the documentation for the theme you select.

Wrapping Up

You now know how to create a Hugo theme from scratch, using regular HTML and CSS, along with a small amount of Go’s templating language. Your layouts are defined in a clear maintainable way, and you’ll add more to your theme in the following chapters.

You’re ready to look at Hugo’s powerful content creation and management features.

Chapter 3
Adding Content Sections

Hugo is designed to help you get your content in front of people quickly. Hugo has a few rules and conventions about how it handles collections of content, and understanding them will let you add and manage entire content sections to your site quickly.

In this chapter, you’ll build a “projects” section of the site that showcases things you’ve accomplished. You’ll create a custom layout for projects so they’re visually distinct from the other pieces of your site, and you’ll use Hugo’s archetypes feature to create a content template so you can create new project pages quickly.

Let’s start with that content template.

Creating a Project Archetype

In ​Creating Content Using Archetypes​, you learned about the default archetype that Hugo automatically includes when you generate a new site. When you created new pages, this archetype acted as a content template, filling in the YAML front matter for you. You can create more specific archetypes for other types of content and include whatever you’d like, including placeholder content.

Create the file archetypes/projects.md and open it in your editor. Add the following to the file, which defines not only front matter, but some placeholder content:

The front matter is nearly identical to the content in the default archetype, which uses some Go template functions to generate the page name from the filename. But unlike the default archetype, you’re adding some content to the body. You specified a placeholder image, a placeholder for the description, and a “Tech Used” section where you can list the various pieces of technology you used. Whenever you generate a new project, Hugo uses this file as the basis, and you can use the placeholder text here to quickly fill out your project’s details.

Save the file and try it out. Create a new project page with the hugo new command:

This generates content/projects/awesomeco.md. The hugo new command creates files in the content directory, and since you prefixed the filename with projects/, Hugo looked for, and found, a projects archetype, which it used to create this file.

When you open the file, you’ll see that Hugo used your new project archetype instead of the default:

Replace the placeholder text with some details associated with the project. Save the file, start up the development server with hugo server, and visit http://localhost:1313/projects/awesomeco to view the project page as shown in the screenshot.

Stop the server and create another project page with the hugo new command:

This creates the file content/projects/jabberwocky.md. Start up the server again. You’ll find this file at http://localhost:1313/projects/jabberwocky.

Joe asks:

Do I Have to Stop and Start the Server Every Time I Want to Add a New File?

No, you don’t. Hugo is usually pretty good at noticing new files. That said, in this book I’m going to prompt you to do so at various times because this ensures you’ll see exactly what you should. It also avoids you having to juggle multiple terminal windows or manage background processes.

You now have a fast way to generate pages that showcase your projects. All you have to do is generate a new page and fill in the details. Archetypes can be fantastic boilerplates that guide you as you create additional content.

Unfortunately, if you visited http://localhost:1313/projects, instead of a list of projects, you won’t see anything at all. That’s because you haven’t defined a layout that displays lists. Let’s do that now.

Creating the List Layout

Up until this point, you’ve only worked with individual pages, like the home page or a project page. You haven’t done anything with lists of content yet. But if you’re looking to show a list of tags, categories, or in this case, projects, you have to define a layout for those named list.html. When you generated the theme, Hugo placed a list layout in the themes/basic/layouts/_default directory, but it’s blank. That’s why you don’t see anything when you visit http://localhost:1313/projects.

Let’s define a default list template that will work for all list pages on the site. Open the file themes/basic/layouts/_default/list.html and add the following code to the file, which displays the title of the content page and builds a list of links to each content page:

The {{ range .Pages }} section is where the magic happens. The .Pages collection contains all of the pages related to the section you’re working with. When Hugo builds the list page for Projects, for example, it collects all the pages within content/projects and makes those available in the .Pages variable in the context. The range function lets you iterate over the results so you can display each record in the collection. Inside of the range block, you access the properties of each page, as the context is now set to that specific page’s context. In this case, you’re displaying the site-relative URL and title of each page.

Fire up the development server again with hugo server and visit http://localhost:1313/projects, and you’ll see a list of your projects. Notice that the heading on the page also shows “Projects”. The .Title variable at the top of the layout file uses the content type’s title:

With this in place, add a Projects link to your main navigation so visitors can find that section. In the exercises at the end of Chapter 2, ​Building a Basic Theme​, you moved your navigation from the header partial to its own nav partial. Open themes/basic/layouts/partials/nav.html and add the link to the /projects url:

The default list layout you made is very generic. It’s a good start and will serve you well when you add other content types to your site later. Let’s create more specific layouts for projects so you can make project pages look a little different.

Creating More Specific Layouts

You’ll often find that you’ll want some pages or sections of your site to have slightly different themes or layouts. Let’s make a specific layout for project pages that displays the list of projects in the sidebar of each project page so that visitors can navigate through projects easier. You’ll use a similar approach to the one you just used to make the list of projects.

In the themes/basic/layouts folder, create a new folder named projects. You can do that on the command line like this:

Then, create the file themes/basic/layouts/projects/single.html. Add this code to define the main block with sections for the content and the project list:

In the project-list section, add the code to iterate over all of your projects and display a link to each page. Since you’re not working with a collection in a list layout, you won’t have access to a .Pages variable. Hugo provides a mechanism where you can access any content collection. The .Site.RegularPages variable gives you access to all of the pages in your site. You can whittle that down with the where function, which works similar to how a SQL statement works. For example, to find all of the Project pages, you’d write this statement:

So, to display the list of all projects, add this code to the project_list section:

You can sort the items too. If you’d like to order them by the most recent project first, use the .ByDate function and the .Reverse function like this:

If you only wanted to display the most recent project, you could do this:

This would be one way to showcase your most recent project on your site’s home page. Note that even though you’re only getting one element, you still treat it like a collection.

Start up the development server, switch back to your browser, and visit a project page. The list of projects shows up at the top of your page. Let’s turn that project list into a sidebar with a little CSS.

Open themes/basic/static/css/style.css in your editor. Locate the media query that targets screens larger than 768 pixels wide, and add the following code to align the project list to the left of the screen in those situations:

The project info and the project list are contained in an element with the class project. Applying display: flex to that element makes the two child elements sit side by side. You then set the width of the project list section to 20%, and you set flex: 1 for the project_info section, which causes the element expands to fill the space. This gives you a nice two-column layout.

Before moving on, let’s look at how to add Markdown content to the page that lists your projects.

Adding Content to List Pages

When you visit http://localhost:1313/projects,you see a list of projects and nothing else. Let’s add some content to the page as well. To add content to list pages, you need to add an _index.md file to the folder associated with the content. This is similar to how you added content to your site’s home page.

Create the file content/projects/_index.md. You can do this with the hugo command:

Open the file in your editor. It’ll have the front matter filled in, and it’ll also have the placeholder content, since it applied the projects.md archetype. Replace the content with some text that introduces your projects:

The list template you created earlier doesn’t display the content. Open themes/basic/layouts/_default/list.html and add code to include the content into the layout:

Make sure both files are saved and view your project list to see the content:

With this in place, all list pages in your site support additional content, not just your project list. However, all of those lists will look the same. Let’s make a layout for the project list next.

Customizing the Project List

Just like how you can create layouts for individual items in a content section, you can control how the list for a content section looks with its own list layout. The default list layout uses a bulleted list, but let’s make a layout for projects with a little more structure.

Create the file themes/basic/layouts/projects/list.html. Define the main block, bring in the page title and the content section, and then iterate through the pages the same way you did for the default list page, but use HTML sectioning elements instead of a list:

Save the file and view the projects list again to see the changes:

In Chapter 4, ​Working with Data​, you’ll add more information about each project to this page, but for now this demonstrates that you can override the default layout for a content section.

Your Turn

1. Add the most recent project to the site’s home page by modifying the index layout for the site.

2. Create a new type of content named “Presentations”. Create the archetype, a new single page template, a list template, a couple of content pages, and wire it up to your navigation.

Wrapping Up

You’ve added a new Projects section to your site so you can show off your projects. Whenever you want to add a new project, you can generate a new content page with ease, thanks to the custom archetype you’ve built. When you want to add new content sections to your site, you’ll follow this same pattern.

Sometimes content comes from other sources, or you want other sites to be able to consume your content. Hugo has some features that let you do both, and you’ll explore those next.

Chapter 4
Working with Data

Modern sites are driven by data. That data might come in the form of content stored in Markdown files, or from external APIs.

You’ve already used some data in your site. For example, you’ve included the site’s title in your templates, and you’ve displayed each page’s title. But you’re not restricted to global configuration data. Hugo has built-in support for incorporating external data files into your site, and it can fetch data from remote sources to generate content in your layouts.

Using Site Configuration Data in Your Theme

Your layouts use {{ .Site.Title }} to display the name of the site in the browser title bar and in your header navigation. You can place all kinds of other data in your site’s configuration file and use it as well.

For example, let’s use the site’s configuration to build additional <meta> tags in the site’s header. The site configuration file has built-in fields like Title, but you can add anything you’d like to this file if you add it to a params section of the file.

Open config.toml and add a new params section that defines the author of the site and a description of the site:

Then, open the file themes/basic/layouts/partials/head.html and add a new author meta tag to the page:

Below that, add one for the description:

Now all of your pages will have these tags filled in. If you open your page in a browser and look at its source, you’ll see the data:

The description field isn’t page-specific yet, but you’ll fix that shortly after you explore how to use front matter data to pull in content.

Populating Page Content Using Data in Front Matter

When you created your Project archetype, you created some placeholder content that you could replace. Over time, you might want to change the content on these pages, and going through each one manually to get them all looking the same could be a lot of work.

Let’s refactor the project pages so they’re more data-driven.

Modify the default archetype for Projects to include the image, the image’s alternative text, and the “Tech Used” content. You’ll also add a summary that you can use in various places:

Notice that you’re using the name of the file to generate some of the default text for the summary, the image alt text, and even the main content.

Generate a third project using this template. Stop your server and execute the following command to create a page for a project called “Linkitivity.”

Open content/projects/linkitivity.md and you’ll see this content:

The name “Linkitivity” is placed throughout the front matter, making it easier for you to maintain consistency.

Before moving on, modify the two existing project pages you created to reflect these changes. Remove the placeholder text and move it all to the front matter section instead, under those keys. For reference, here’s what your Awesomeco project should look like:

Next, modify the project layout to use this data. Open themes/basic/layouts/projects/single.html and locate the {{ .Content }} section. Below that line, add code that adds the image and alternative text from the front matter, and then iterates through the values in the tech used field to display those values on the page:

Notice that the image, alt_text, and tech_used fields are prefixed by .Params. Any custom fields you add to the front matter get added to this .Params collection. If you don’t add that prefix, Hugo won’t be able to find the data. Fields like description and title are predefined fields that Hugo knows about, so you don’t need the params prefix when referencing them. You can find the list of predefined fields in Hugo’s documentation.^[18]

Save the layout and start the development server with hugo server. Visit http://localhost:1313/projects/awesomeco.md and your project displays, but this time it’s driven by front matter data instead of hard-coded content:

This will give you a much more uniform approach for adding projects. There’s absolutely nothing wrong with continuing to define your content using the method you used before, where you used placeholder content, but you might find this method more appropriate for things that need to be developed in a more uniform fashion. However, by taking advantage of Hugo’s data-driven features, it’s easier to make list pages more interesting.

The information you’ve added to the front matter is available in other templates. Let’s add the information in each project’s summary field beneath each entry on the project listing page, so it’s more than just a list of projects. Open themes/basic/layouts/projects/list.html and add the summary beneath the project link:

Save the page and visit http://localhost:1313/projects. The summaries now appear after each header as shown in the screenshot.

Remember, when you’re working with range, it’s iterating over each entry. Inside the block, the range is pointing at the current entry, so you can access any of the properties of that item, including content or front matter data.

In addition to displaying data, you can also use the data in pages to make decisions about what to display.

Conditionally Displaying Data

Earlier in this chapter, you added a <meta> tag for the description of the page, but it’s good practice to have that description reflect what’s actually on the page. You can add conditional logic to your layouts to control how you display data. For example, you can check to see if there’s a description field set on the page, and if there isn’t, you can fall back to the site-level description.

Hugo has an isset function which, at first glance, looks like a great way to check whether a variable has a value. Unfortunately, it has limitations that aren’t intuitive. It doesn’t handle situations where values are always defined but are empty, like default values. The Description field on a page is actually a default field. If you don’t define it in your page, its value will be defined, but empty, and isset won’t work.

To handle cases where you’re checking for a value in a default variable like this, use Hugo’s with function. Replace the existing meta description in themes/basic/layouts/partials/head.html with this block of code, which conditionally sets the description:

The with function rebinds the context. Using with, you can switch the current context to .Page.Description. Then within that block, a single period prints out the value. But the with function has a nice side effect: if the value of the context is empty, then the block gets skipped and nothing gets rendered. To handle the case where there’s no description, you pair the with function with an else statement.

Save the head partial. To test this new behavior, open the content file for the project list page at content/projects/_index.md and add a description field:

Save the changes and visit the projects list page at http://localhost:1313/projects. Inspect the source and you’ll see that the description meta tag now shows the more specific description. You can now add the description field to other content pages’ front matter.

Joe asks:

What’s the Difference Between summary and description in Front Matter?

The difference is mostly up to you. In some cases, they might be the same content. However, the description field is great for providing a description of the page optimized for search engines or social sharing, while the summary field gives you a chance to create a short summary of the content you’ll display on other parts of the site. As you’ll see later in this chapter, Hugo can automatically generate a page’s summary, but the summary field in the front matter overrides that, giving you more control.

The <title> element currently uses the title of the site and doesn’t accurately reflect the title of an individual page. This can be bad for search engine ranking, but it’s also bad from a usability standpoint. The value of the <title> tag is what appears in the browser title or bookmark tab, as well as a bookmark someone creates.

Let’s use the default site title on the home page, and use the more specific page title everywhere else. To do this, use an if statement with the built-in .Site.IsHome variable to check to see if you’re on the home page or not and display the site title or the more specific page title. Modify the head partial and replace the existing <title> tag with this code:

Notice that this code appends the site title to the page title, which is a common practice when optimizing your site for search engines, as the page title shows up as the title in search results. With these changes in place, your page’s data more accurately reflects the specific page.

Sometimes you might want to drive sections of your site from other data sources. Let’s look at how to do that.

Using Local Data Files

The data directory can hold structured data files in YAML, JSON, or TOML formats that you can use in your layouts to display content. You could write these data files by hand or extract them from other sources.

Let’s try this feature out and use it to add social media profile information to the contact page of the site. Instead of embedding your social media accounts in your layout directly, you’ll define them in a JSON file. Then in your layout, you’ll load the file and iterate over its contents and display the data.

Create the file socialmedia.json in the data directory of your site. In the new file, create an accounts property with an array of accounts. In the array, represent each account as an object with a name and url property, like this:

Save the file once you’ve entered in your accounts.

To use this data file, you must use a layout to read the file in and use it. Content pages can’t directly include dynamic content. In ​Using a Shortcode to Process Images​, you’ll learn how to make functions you can include in your content pages that can get dynamic content. For this example, you’ll make a specific layout for the contact page of the site, instead of relying on the default single.html layout.

Add this new layout to the site’s layouts directory, rather than as part of the theme, since this is a specific customization. You can incorporate this into the theme later if you find it useful. Create the file layouts/_default/contact.html and add the following boilerplate to define the main block and display the title and content:

Then, right below the {{ .Content }} line, add this code, which loads the data and iterates over it:

Save the file. The layout you created won’t override the default single page layout because it’s not associated with a specific type of content. When you created a layout for projects, Hugo automatically associated the layout with all content within the projects folder. In this case, there’s no association like that, so you have to explicitly assign the layout file to the contact.md Markdown file. Open content/contact.md and specify the contact layout in the page’s front matter by adding the following code:

Save the file, fire up the development server with hugo server, visit http://localhost:1313/contact in your browser. Your social media links are now displayed on the page:

Sometimes the data you want comes from an external site. Let’s look at how to handle that.

Pulling Data from Remote Sources

You’re not limited to using local data. You can use Hugo to fetch remote data and process it every time you build the site.

Let’s create a page of the site that shows your public GitHub repositories.

To get that data, you will use the GitHub API and then make a request to https://api.github.com/users/<your username>/repos. This returns a JSON collection of all your repositories and doesn’t require any authorization.

Store the API URL and your GitHub username in the site’s configuration file, rather than directly in the layout. Open config.toml and add two new fields to the params section to hold these values:

Then, create a layout for this file in themes/basic/layouts/_default/opensource.html. Unlike the contact page you created, you’ll keep this with your theme. Add the usual boilerplate to the file:

Next, right after the {{ .Content }} line, add the following line of code to build up the GitHub URL using your username from the site’s configuration:

This defines a $url variable and uses Go’s printf function to concatenate the base URL, your username, and the /repos endpoint. Note that you have to use .Site.Params as a prefix on both of these, as you stored them in the site’s configuration.

Now, add this line to make the request for the JSON file using the $url variable you built:

This makes the request and fetches the JSON data into a collection that works like the other collections you’ve used. From here, you can use the range function and iterate over the results. Each result has a name, url, html_url, and description property, so use those to build a list of your repositories, like this:

The html_url property points to the URL of the repository, while the url property points to the API endpoint, which you could use if you wanted to fetch even more details about each project.

Every time you rebuild the site, Hugo will make a request to the GitHub API and pull in this data. Since the data about your repositories doesn’t change that often, this level of caching is perfect. However, if you don’t want to hit the API every time you build, you can download the JSON data, store it in your data directory, and load it in like you did with your social media links on the contact. If you take this approach, remember to refresh your local file periodically.

Next, create a new content page for your site called opensource.md which will use this layout. Stop the development server and use the hugo new command to create this file:

Open the newly created content/opensource.md file in your editor. Ensure the draft status is false, set the title to “Open Source Software”, and ensure it uses the opensource layout. Below the front matter, add a paragraph of content that introduces the page content. Your completed file should look like this:

Let’s add some CSS to transform the list into a series of tiles. Open themes/basic/static/css/style.css and add the following code:

Flexbox once again comes to the rescue. The oss container becomes the flex container and specifies that child elements should wrap and be spaced out equally. The inner article elements get a width, margin, a border and a small drop shadow. The result is a series of tiles nicely spaced apart.

Ensure all of your files are saved and start up the development server with hugo server. Visit http://localhost:1313/opensource and you’ll see your projects displayed as tiles as shown in the screenshot.

Now, whenever you create a new project on GitHub, it’ll show up when you regenerate the site.

Joe asks:

How Would I Generate Content Pages from Data?

Hugo is a static site generator that converts existing content documents into web pages. It doesn’t have any built-in ability to generate content pages from data, but you can still make it work.

For example, you could write a small script that reads the data and generates Markdown documents, which it stores in the content folder. Then, when you run hugo to build the site, the generated pages will be included.

Hugo’s developers want Hugo to stay focused on fast website generation. As a result, you’ll often find that you’ll rely on tools outside of Hugo for more complex situations.

Before moving on, add the link to your open source projects page to your project list page. Open themes/basic/layouts/projects/list.html and add the link on the page like this, along with its summary:

Instead of using a hard-coded link, you’re grabbing the title and URL from the page using Hugo’s GetPage function, which takes the path to the Markdown file. Using this method, you can pull data from any page into your layouts.

The front matter for the open source page doesn’t have a summary field, so you’re probably wondering where the summary will come from. Hugo gets it by reading in the first few sentences of the content for that page. You’ll take more control of auto-generated summaries in Chapter 5, ​Adding a Blog​.

Visit http://localhost:1313/projects to see your open source projects displayed above the other projects:

So far you’ve used Hugo to generate HTML pages, but you can also generate other formats too.

Syndicating Content with RSS

Hugo creates RSS feeds for your site automatically using a built-in RSS 2.0 template. If you visit http://localhost:1313/index.xml, you’ll find a pre-built RSS feed that includes all of your pages and looks something like this:

Hugo generates RSS feeds for your sections too. Your projects have their own feed at http://localhost:1313/projects/index.xml.

People won’t know there’s a feed for your site unless you tell them about it. To make your feed discoverable, you can add a meta tag to your site’s header that looks like this:

RSS readers and other tools can use this tag to identify the RSS feed automatically.

Add this code to your themes/basic/layouts/partials/head.html file to add links to any alternative formats associated with your page:

This iterates over all of the alternative formats associated with the current page. Right now there’s only one, but you may add more in the future. Each content has a type attribute. Hugo will attempt to escape special characters when you print values using the {{ }} notation. One of those values is the plus sign in application/rss+xml, the value associated with RSS feeds.

To avoid escaping special characters, use the printf function to inject the values. Note the backticks around the value for the $link variable. By using the backticks, you don’t need to escape the double-quotes for the HTML attributes.

The title attribute should reflect the title of the page, so you detect if this is the home page or not, and assign the proper title to the $title variable. This is similar to how you set the value for the <title> tag. However, since the range function is operating on the collection of alternative formats, the current scope is limited to values in that collection. Prefixing the scope with a dollar sign tells Hugo that you’re looking for values in the global scope rather than in the current local scope. That is why you use $.Page.isHome here instead of .Page.isHome.

The final printf statement creates the <link> tag. The safeHTML at the end ensures the HTML snippet itself isn’t escaped. Be careful with safeHTML; only use it with HTML snippets you create, and use it sparingly. Never use it on snippets you don’t trust.

When you visit http://localhost:1313/ in your browser and look at its source, you’ll see the RSS link generated:

Since this link to the feed is generated using the .Permalink function, Hugo will use the value of the baseURL field in the config.toml file when you build the site. When it comes time to deploy the site, you’ll specify that value so everything works properly.

If you visit http://localhost:1313/projects/, you’ll see the link for that page as well:

Hugo can support many output formats. Let’s use Hugo to generate a JSON file that lists your projects.

Rendering Content as JSON

Hugo supports JSON output out of the box too, which means you can use Hugo to create a JSON API that you can consume from other applications. Unlike RSS feeds, you need to create a layout for your JSON output, and you must specify which pages of your site should use this output type.

To explore this, you’ll make a JSON list of your project pages containing the title and URL for each project page, which you can then consume from other applications. The resulting file will look like this:

First, create a JSON template file at themes/basic/layouts/projects/list.json.

In the new template file, create a JSON template that iterates through your project pages and displays them:

Entries in a JSON array need a comma between each entry, but they don’t need a comma after the last entry. By using an index as you iterate through the entries, you can insert the comma in front of the current entry. Note that you’re using the {{- form for the templates, which suppresses whitespace in the output, depending on where the dash is located. Remember from ​Using Content Blocks and Partials​, that adding the dash after the opening braces suppresses whitespace characters in front of the output, while adding a dash in front of the closing braces suppresses whitespace that follows. Suppressing whitespace like this will result in JSON that’s more readable by humans.

Hugo won’t generate the JSON file until you configure it to do so. You can configure output formats in the main configuration file, but you can only specify that for the home page, all sections, and all content pages. To apply the output to a specific section of the site, you specify it in the front matter of the section’s page.

In this case, the output formats need to be specified in the project list content page. Edit the file content/projects/_index.md and add the following front matter to tell Hugo to generate a JSON file in addition to the HTML and XML files it generates by default:

Save the file and then run hugo server. Visit http://localhost:1313/projects/index.json and you’ll see your file.

You might be thinking that the URL is a little ugly, and you’d like to change it to /projects.json instead. The url field in a page’s front matter lets you change the URL for a page, like this:

Unfortunately, if you add that line to the content/projects/_index.md file, Hugo will no longer render the HTML page. Hugo doesn’t have a way to handle different URLs for different types. If you wanted to change the URL for your project feed, you have two options.

The first option is to configure your web server to rewrite the URL. The second (and much easier) option is to move the file before you upload it to your server. In other words, move projects/index.json to projects.json. You could do this as part of a larger build and deploy process like the one you’ll create in ​Using Webpack and npm with Hugo​.

One last thing: if you visit http://localhost:1313/projects/ and look at its source, you’ll see a <link> tag for your JSON feed next to your RSS feed. The loop you created to display your RSS feed iterates through all of the alternative formats for a page, so this JSON feed gets included.

Your Turn

Before moving on, see if you can complete these challenges:

1. Add keywords to the front matter of your home page and content pages, and add a <meta name="keywords"> tag to your site’s heading.

2. Change the footer so it uses the author name in the site’s configuration file in the copyright notice.

3. Incorporate the social media links into your site’s footer. Include the code in a partial.

4. Download your repository data to a local JSON file and modify the template to read that local file instead. Once you have it working, revert the change so the data is pulled directly from GitHub again.

5. Dive deeper into how whitespace suppression works in Hugo templates by adding and removing dashes in your list.json template. Make a change and then review the source of the file in the browser. Notice how changing {{ to {{- or }} to -}} affects how the JSON is formatted.

6. Add additional fields to the JSON file for your project feed.

Wrapping Up

You’ve integrated some JSON data into your site. You’ve got social media links coming from a local file, and you’ve loaded your GitHub repositories from GitHub’s public-facing API. In addition, you used data from the configuration file and individual front matter sections throughout your site. Combined with what you’ve learned in previous chapters, you have all the tools to add a blog to your personal site, which you’ll do next.

Chapter 5
Adding a Blog

When you want to share your thoughts with the world, using your own site is one of the best ways to do it. While there are platforms you can use to do this, choosing to instead host from your own domain offers certain benefits. You can measure its effects, control how the information is presented, and more importantly, build your own brand with content you own. When you publish content elsewhere, you have to opt in to their terms of service, and sometimes hand over control over your content and community.

To simplify the process of hosting your own content, you can use Hugo to add a blog to your site. To create a blog in Hugo, you’ll create a new content type, named “Post”, and you’ll create layouts to support displaying those posts. A lot of what you’ll do in this chapter will build on what you’ve done previously, but you’ll apply it in new ways. In addition to creating the content type, you’ll incorporate a third-party commenting system into your static site, and you’ll implement pagination so you can support future content growth.

A post on a blog has a title, an author, and some content. It might have a summary as well. You might want to put your posts into categories and tag them. You can manage most of this from the front matter of each piece of content much like you did with projects.

Start by creating an archetype for a post so you have a blueprint to follow. Create the file archetypes/posts.md by copying the default archetype file:

Then, add an author field and add your name:

Next, add some default content to this file. Any placeholder text will do, like Lorem Ipsum:^[19]

The <!--more--> line lets you specify where the content summary ends. As you learned in ​Pulling Data from Remote Sources​, when you use {{ .Summary }} in a layout, Hugo will pull the summary from the front matter or by generating it from the content. Sometimes that auto-generated summary ends in an awkward place. To control where the summary should end, add <!--more--> to the content.

Save the archetype and use it to generate an initial post to test things out:

Visit http://localhost:1313/posts/ and you’ll see your post listed. This list is generated using the default list layout, which you’ll customize later. Let’s flesh out the layout for an individual post.

Creating the Post’s Layout

The page for an individual post is bare because it’s using the default single page layout. Like with project pages, there’s information in each post’s front matter you can use on the page. To do that, create a new single page layout for posts.

Create the directory themes/basic/layouts/posts/ to hold the layout. You can use your editor or use the following command in your terminal:

Then create the file themes/basic/layouts/posts/single.html, which will hold the layout for an individual post.

Create the main content block and place the title and post content in their own sectioning elements with classes; this will help you style them later:

Within the header section, add the byline, which will contain the publication date and author name. The .Date field will fetch the date, and the .Format function will let you format it in a similar fashion to how you formatted the date in the footer.

Many blogs will display the amount of time it takes to read the content at the top of an article. Let’s add that to our blog page template.

The average person reads anywhere from 200 to 250 words per minute^[20] depending on several factors. If you count the number of words in a page’s content and divide it by 200, you’ll get a conservative estimate of the number of minutes it’ll take to read your content.

Hugo has built-in functions for counting words and doing math, so in your template, add the following code to your byline to determine and display the reading time:

To make sure this works, add a significant amount of content to your first blog post so there’s some text to count.

Save the file and visit http://localhost:1313/posts/first-post.md. The author, date, and reading time display above the post:

As you build out more content, you’ll probably want to organize and group it so it’s easier for people to find.

Joe asks:

Does Hugo Support Syntax Highlighting for Code?

If you’re publishing posts, you might want to include snippets of code from time to time. Hugo supports syntax highlighting using a library named Chroma,^[21] which is compatible with the popular Pygments^[22] syntax highlighter.

To configure this, tell Hugo you want it to use Pygments-style classes when it highlights your code. Add this line to config.toml:

​	pygmentsUseClasses = ​true​

Then, generate a stylesheet to highlight your code using one of the available Chroma styles:^[23]

​	​$ ​​hugo​​ ​​gen​​ ​​chromastyles​​ ​​--style=github​​ ​​>​​ ​​syntax.css​

Add the syntax.css style to your head.html partial.

Now, when you write your posts, use code fences and specify the appropriate language:

​	​```javascript​
​	​let x = 25;​
​	​let y = 30;​
​	​```​

Hugo will apply the styles to your code.

Organizing Content with Taxonomies

Many blogs and content systems let you place your posts in categories and apply tags to your posts. This logical grouping of content is known as a taxonomy. Hugo supports categories and tags out of the box and can generate category and tag list pages automatically. All you have to do is add categories and tags to your front matter.

Open the posts archetype at archetypes/post.md and add some default categories and tags:

Adding these defaults to the archetype won’t affect the content you’ve already created, so open content/posts/first-post.md and add categories and tags there too:

Both categories and tags are lists of items, so you need to use the correct notation in YAML. Hugo supports TOML and JSON front matter as well, so you could use those for your posts instead if you find those easier to manage.

By adding the tags and categories to your post, Hugo will generate pages for those using your default list layout. Visit http://localhost:1313/tags to see the tags list:

Selecting a tag shows you a list of all of the pieces of content associated with that tag.

Visit https://localhost:1313/categories to see the list of categories:

When you visit https://localhost:1313/tags, you’re looking at what Hugo calls “taxonomy terms.” When you look at a specific tag, that’s what Hugo calls a “taxonomy.” This becomes important when you’d like to customize the layouts for these pages. Let’s alter the tags list so it shows the count of items associated with each tag in addition to the tag.

To customize the page that displays the list of all of your tags, create a new layout named tag.terms.html. Place it in themes/basic/layouts/_default/.

In the new file, add the usual layout boilerplate, including the title and the {{. Content }} pieces. Instead of iterating over the related pages like you have done in previous list templates, iterate over all of the tags for the site with .Data.Terms. This will give you access to the number of content pages associated with each tag:

You’ve included {{. Content }} in the layout. When you’re looking at the /tags section of the site, Hugo will look in content/tags/_index.md for that content. Create the _index.md file now using:

Open the file in your editor and add some content:

Now, visit http://localnost:1313/tags and you’ll see your tag list with counts and the associated content:

When you select a tag, Hugo looks for a layout associated with tags. If you want to customize this layout, create a layout named tags.html in the theme/basic/layouts/_default folder and use the same logic you use in your existing list layout to pull in the content. When you’re displaying content for a specific tag, you’re not interested in the collection of tags; you’re interested in the pages associated with the tag.

Before moving on, add the list of tags to the post’s single layout. Open themes/basic/layouts/posts/single.html.

To display the tags, iterate over the tags in the front matter using .Params.tags and the range function:

The tags listing page is located at /tags, and each tag itself is located at /tags/tag-name. As you iterate over each tag, you can construct the link to each tag by appending the tag name to /tags/. However, since tags might contain spaces or other characters, use the urlize function to encode the tag as a URL-safe string.

Each link in the tag list has a class of tag so you can more easily style the entries in the list. Open themes/basic/static/css/style.css and add the following CSS to change each tag into a gray button:

When you add padding to each tag so that the background color doesn’t touch the words, the boxes will become larger, so you can decrease the font size to make up the difference.

Visit http://localhost:1313/posts/first-post to see the updated byline with the tag list:

Your individual post page looks good, and you’ve got tags and categories configured. Now let’s look at customizing the URLs for your posts.

Customizing the URL for Posts

By default, your blog contents show up under posts/. For example, your first blog post is available at http://localhost:1313/posts/first-post. Many blogs use the year/month/title format for their blog post URLs. This meaningful URL shows anyone looking at the URL how old the post might be, but it also shows that the content is organized by date. In sites with content organized like this, a visitor could see content for the rest of the month, or for the whole year, by specifying the year or month.

A permalink is a permanent link to a specific page, often used when sharing a page with others through social media, newsletters, or even search results. You can use front matter on a post to control the permalink for a post by using the url field, but that’s really only meant to handle situations where you’re migrating content or need to do some one-off customization. Hugo lets you define how you’d like to structure your links in its configuration file.

In config.toml, add a new Permalinks section and define a new rule that makes posts available under /posts/year/month/slug:

This gives you URLs like /posts/2020/01/first_post. The slug is the end part of the URL that identifies the page’s content. It’s generated from the page title by default, but you can define your own slug by adding a slug field to your page’s front matter section.

If you visit /posts/2020, you might expect to find a list of all posts for that year. Unfortunately, Hugo doesn’t support generating these pages currently, at least not without a little extra work.

However, one of Hugo’s maintainers offered a practical workaround.^[24] By using Hugo’s taxonomy feature and a little clever use of front matter, you can generate archive pages of posts for years and months. You’re going to add “year” and “month” as new taxonomies, and “tag” your posts with a year and month. Hugo can then build the year and month pages for you just like it builds pages for categories and tags. You’ll use this approach with some minor tweaks to build out your pages.

First, add year and month fields to your content’s front matter. For the year, use the four digit year. For the month, use the four digit year, a forward slash, and the two digit month. For example, for a post written in January of 2020, you’d add these fields:

Open content/posts/first-post.md and add the year and month fields:

Adding these fields every time you create new content on your blog is going to get old pretty quickly, and it feels redundant. You can generate these in your posts.md archetype. It’s already getting the date, so create these fields in the archetype and extract the month and year:

The dateFormat function uses Hugo’s date formatting strings and applies them to the given date. Now when you generate new pages for your site, the month and year front matter will be created. Create a new post for your site to verify that these front matter changes work:

Open content/posts/second-post.md to verify that the month and year is set:

Next, open your site’s configuration file and define permalinks for the year and month pages. Add this code:

Finally, to generate the archive lists, define the year and month data as new taxonomies. To do this, add a taxonomies section to the configuration file, like this:

When you define a taxonomies section in your configuration, it replaces the defaults. To keep support for tags and categories, you have to explicitly define them now that you’ve customized things.

Save the configuration file. Your default list layout will handle the actual display of the posts, so when you visit /posts/<year> or /posts/<year>/<month>, the posts for that section will show.

They don’t look very good, though, so let’s fix that.

Customizing Blog List Pages

The list of posts isn’t very appealing since we’re using the default list layout. Let’s make a layout for posts that shows the title, post date, and a summary of each post’s content.

You’ll need to make a main posts list showing the most recent posts, but you’ll want to do the same thing for your “year” and “month” list pages. Since there’s going to be significant duplication, you can make a partial to hold the bulk of the markup for a post and share that across layouts.

Start by adding that partial. Create the file themes/basic/layouts/partials/post_summary.html. In the file, add the following code, which renders the post’s title, publication date, and summary in an <article> element:

Save the file. Now create the file themes/basic/layouts/posts/list.html and add the following code, which iterates over the pages and uses the partial to display them:

Save the file and visit http://localhost:1313/posts to see it in action. Each post displays, with the most recent post first, and its abstract displays as well:

This layout only works for posts. It won’t work for taxonomy pages like your year and month archive pages. To make that work, you’ll need more specific layouts. You defined the year and month pages as new taxonomies, so create the files year.html and month.html in the themes/basic/layouts/_default directory with the same code as the post list layout. To speed up the process, copy the existing list page. You can do that your editor, or with the following commands if you’re using macOS, Linux, or WSL:

The cd - command returns you to the previous directory.

Once those files are in place, start up the server again with hugo server and visit http://localhost:1313/posts/2020. You’ll see the posts for that year displayed:

With your list page complete, add your blog to the site’s navigation bar. Open themes/basic/layouts/partials/nav.html and add a link to your posts page:

Save the file. Your navigation bar now contains a link to your blog.

As you get more content, your list page might become quite long. You can break things up with pagination.

Adding Pagination

Once you have more than a handful of posts, your archives pages are going to get very long. And your main blog list page will grow and grow until it’s too big to be useful. To handle this, you can break up the list of results into multiple pages, with links to navigate between the list pages. This process is known as pagination.

Hugo has built-in pagination support, and it’s enabled by default. All you have to do is change how you fetch pages and add pagination navigation to your layouts.

To use pagination, use .Paginator.Pages instead of .Pages in your range statement, like this:

Hugo defaults to showing 10 pages at a time with its paginator, but you can override this in the layout. Let’s explore this by applying pagination to the list layout for posts.

First, create another post in your site so you have more than two pages. Use hugo new to create the page:

Then, open themes/basic/layouts/posts/list.html and modify it to use the paginator and the built-in pagination template. For now, set the number of pages to show to 1 since you only have three pages and you’ll want to be able to test out the navigation:

Save the file. When you view the site, the pagination won’t look very pretty as shown in the screenshot.

Hugo’s internal pagination template uses markup compatible with Bootstrap,^[25] the popular CSS framework. Since you’re not using Bootstrap in this theme, you’ll have to whip up a few styles. If you view the source of your page in the browser, you’ll see markup like this for the pagination:

Hugo’s pagination template generated a list of links with various classes that you can use to style the elements. There are classes to identify the active elements, disabled elements, and regular elements.

To style this quickly, use a method similar to how you styled the navbar and use Flexbox. Open the themes/basic/static/css/style.css file in your editor and add the following code to style the pagination container:

On larger screens, you constrain the width to be 30% of the page. The margin: 0 auto line centers the element horizontally.

Next, add this code to define how each pagination button looks by giving it a border and some width:

Then style the individual links. Set each link to display: block so it fills the parent container. This makes the links easier to click, as the click target is the entire box, rather than the text:

Finally, add code to change the colors for the active page link and the disabled links:

View the posts page, and this time you’ll see styled pagination:

Now that you know the pagination works, open themes/basic/layouts/posts/list.html and change the number of paginated results to 10 posts:

Alternatively, since the default is 10, change the range line back to the original code:

You can then control the number of results globally in the site’s configuration by adding the Paginate field to config.toml:

With pagination in place, your blog list pages will be more manageable for your visitors. Now let’s add interactivity to your blog posts with comments.

Adding Comments to Posts Using Disqus

Many blogs include a commenting system that lets your community of readers interact with your posts. Hugo only generates static sites, but you can add support for comments using Disqus,^[27] a platform that hosts comments and provides tools for community moderation. Hugo has built-in support for Disqus. To use it, you’ll create a Disqus account for your site, set the site name in your Hugo site’s configuration file, and include the Disqus template on your pages.

Create a new account on Disqus for your site. Once your account is created, select the option to use Disqus on your site. Disqus will ask you to provide a few pieces of info about your site:

Fill in the name of your site and select the appropriate category. Take note of the URL that Disqus shows under the Website Name field; you’ll need the first part, which Disqus calls the “shortname,” to link your Hugo site to Disqus. In the preceding image, the URL for the site is pp-hugo-demo.disqus.com, so the shortname is pp-hugo-demo. Press the Create Site button to continue.

Next, select a plan. You can pay for Disqus or use the free ad-supported tier.

Once you’ve selected your plan, you’re presented with options to integrate Disqus with your site. Scroll to the bottom and choose the option to set up Disqus manually. This presents you with some code snippets you can add to your website. You can ignore this, as you’ll use Hugo’s built-in Disqus template shortly. Continue to the Configure Disqus option.

The Configure Disqus page lets you fill in the website URL, the description, and a few other attributes. You don’t need to fill these in now either. Press the Complete Setup button.

Then, open config.toml and add the following line to tell Hugo the shortname for the Disqus site you configured:

In this example, the shortname is pp-hugo-demo. Save the file and then stop the Hugo server and restart it again, just to make sure the new setting is applied.

Next, open the blog post layout at themes/basic/layout/posts/single.html, and after the article contents, add a new comments section that uses Hugo’s built-in Disqus template:

This template uses the disqusShortname shortname variable you set in config.toml and pulls in the Disqus commenting interface for this page. Save the file.

As it turns out, Disqus won’t load if your site is served from the localhost domain, so you won’t be able to see it in action. To get around this, you have a few different options:

• Host the site via a fully qualified domain name.

• Edit your local hosts file and create an entry like example.com that points to your local machine. Then visit http://example.com:1313 in your browser.

• Use a tunneling service and its client to proxy connections through external servers.

We’ll use the last approach, as it also offers an easy way to share your work with others while you’re developing your site. The service localtunnel.me^[28] is a free service that lets you do this quickly using their command-line client. The client is written in Node.js, which means you need Node installed on your local machine.

Use the npx command, included with Node.js, to launch the localtunnel client and proxy your site. Ensure the Hugo server is running, open a new Terminal window, and execute this command:

This downloads the localtunnel package and executes its binary. The -p flag specifies on which port your development server is running.

Use the URL you see in your terminal to access your site. Visit one of your posts and you’ll see your Disqus comments section at the bottom of the page:

As it stands now, you’ve added comments to every blog post. However, you might occasionally want to disallow comments on a page.

Open the first-post.md file and add a new piece of front matter that turns comments off:

Then, modify the post layout to use this value to determine whether or not the comments should display:

Return to your browser and visit the “First Post” page; you’ll see that comments are disabled for that page. Visit one of the other posts to ensure that you can still comment there. When you deploy your site to production, visitors will be able to comment and discuss your content, but only on the posts you choose. Remember to use Disqus’s interface to manage and moderate the comments people leave on your site though.

Switch to the terminal window that’s running the localtunnel server and use Ctrl+c to shut it down. You can then close the terminal window as you won’t need it anymore.

Your blog is almost complete. Let’s add one final feature: showing people other posts related to the one they’re reading.

Displaying Related Content

When people find a page on your site through a social media share or a search result, you might want to make some of your other content visible as well. Hugo lets you display related content and has some sensible defaults for doing so. To enable this feature, you have to add some keywords to your pages’ front matter section. You also have to add some code to your single page template that displays the related content. To demonstrate, let’s add a keywords section to the front matter of the Jabberwocky project and the second-post blog post.

First, open content/projects/jabberwocky.md and add the keywords section. Like tags, it’s a list:

Add the same keywords section to content/posts/second-post.md:

Then, open themes/basic/layouts/posts/single.html and add this code below your post but above the comments section:

This code uses a with block to check if there’s any related content. If there is, it displays the header and the list of content.

By adding the same keyword to the Jabberwocky project and the “second post” blog post, the Jabberwocky project now shows up as a related piece of content as shown in the screenshot.

This is a great way to make people aware of your work. Add keywords throughout your pages to get them to show up on your blog posts.

Hugo uses these default settings for related content, creating indices on the keywords and dates of your content:

To change the behavior of related content, you must add the entire configuration block to your config.toml file and then modify it to suit your needs.

There are a few options you might want to explore when setting up the related post content. For example, the includeNewer option, if set to true, will update older pages on your site with new related content. The threshold is a number between 0 and 100, with lower numbers showing more content with less relevance. Also, the toLower option can increase the matches by lowercasing the keywords and queries that get created for finding related content.

You can also add new indices for tags, author, or any other front matter fields for that matter. The weight for each index you create controls how relevant this index is compared to others. Experiment with these values to get the right balance for your content.

Your Turn

Before moving on to the next chapter, complete the following tasks:

1. Create a layout for the tag pages using the same approach you used for year and month pages. Create the tag list template in themes/basic/layouts/_default/tags.html.

2. Create layouts for the /categories page and the individual category pages.

3. Add an optional header image for your blog posts. Images go in the static folder, and you link to them using the same approach you use when you link your CSS files. Use front matter to define the banner image for a post and display it if it exists.

4. Apply pagination to your project list.

5. Place your latest blog post on the home page of your site.

Wrapping Up

You’ve applied what you learned about creating content sections and data to build a blog. You’ve gained a few new skills as well. You know how to customize URLs for sections of your site, you can organize content using taxonomies, and you can add comments using Disqus to your pages.

With all this new content, you’ll need a way for people to find it. So let’s look at how you can integrate search into your site.

Chapter 6
Adding Search to Your Site

Once you’ve created a large amount of content on your site, you’ll want to make it easier for people to find things. When your site is live for all the world to see, you’ll want to make sure everyone can find your content.

You’ll also want a local search engine for your site, especially for situations where you have a significantly large corpus of content.

Database-driven sites like WordPress have built-in search capabilities. When a visitor seearches for content, their keywords are used to build a query that gets sent to the database containing the content. The database returns results that match, and the system displays the page.

For static sites like Hugo, you’re working without a database, so you’re going to have to think about solving the problem differently. You can use a third-party search service like Algolia,^[29] which indexes your content and lets you search it. You can set up your own search indexer like ElasticSearch^[30] and integrate it into your site. Or you can generate your own search index and use client-side JavaScript to perform the search.

In this chapter, we’ll take the last approach. You’ll build a client-side search engine using a JavaScript library called Lunr^[31] to do the heavy lifting. Lunr needs a list of your site’s content in JSON format, so you’ll leverage Hugo’s ability to generate JSON to create that list.

Creating the Document Collection

For Lunr to search your site, it needs to know about all of the documents available, and it’ll need the titles and some text to search. Lunr accepts a collection of documents that looks something like this:

To generate the search index that Lunr needs, you’ll use an approach similar to how you generated the projects JSON feed; you’ll create a layout for the search index that iterates through all of the pages in the site, emitting the fields that Lunr will use. Later, you’ll fetch this JSON file from the server using JavaScript, parse it with Lunr, and match it against the search terms your visitor provides.

Create the file themes/basic/layouts/_default/search.json and add the following code which iterates through all the pages in the site and displays the title, the body, and the link to the page:

The .RegularPages collection gives you access to all of the pages on the site. You’ll need the link to the page when you eventually display the search results to the visitor.

Next, create the Search content page itself. It won’t have any content, but you need it so you can specify the output formats. Define both an HTML and JSON format, as you’ll create an HTML layout which will display the actual search interface shortly.

Create content/search.md:

Modify the file’s front matter so it displays the output formats. Use layout to associate this file with the search layout you created, and make sure draft is set to false:

Save the file. This is enough to generate the search index. Start the Hugo server and visit http://localhost:1313/search/index.json and you’ll see your documents:

You now have a single JSON file that contains the entire contents of your site. Let’s build the page that displays the search box next.

Joe asks:

Won’t the Search Index Get Huge If I Have a Lot of Content?

Yes it will. And a large JSON file will take longer for your visitors to download and longer for Lunr to index. You might consider using the summary instead of the entire content. This will reduce the size of the file, but will also reduce the reliability of your searches, as they’ll have less to work with. In that case you can explore other options. On a site like this, a single search index such as this one won’t cause any serious performance issues. On sites with thousands of pages, a solution like Algolia will probably be a better fit.

Creating the Search Interface

Right now, when you visit http://localhost/search in your browser, you see the title. The search.md file you created renders output in both JSON and HTML formats, but you only created a JSON layout. The default single page layout is currently applied, but you didn’t define any content in the search.md file. Let’s get the search form to appear on the page.

Create the file themes/basic/layouts/_default/search.html and add the following code, which defines the main block, displays the title, and defines a text box, button, and area for search results:

Save the file. Visit http://localhost:1313/search in your browser and you’ll see the form as shown in the screenshot.

At this point, the form doesn’t do anything. To implement the search functionality, you need to write some JavaScript and attach it to this page. You’ll fetch the document collection you just created, use the Lunr library to build a search index from that document collection, and perform a search using the text your visitor submits.

You’ll use the Axios^[32] library to fetch remote data. Axios is a promise-based library that makes grabbing remote data a breeze.

To use Lurn and Axios, you need to include them on your page. Open themes/basic/layouts/_default/search.html and, right before the {{ end }} markup, add these two lines to load the Lunr and Axios JavaScript libraries from a Content Delivery Network (CDN):

Using a CDN saves you the trouble of downloading them locally, and lets you take advantage of the caching mechanisms the CDN provides. In the next chapter, you’ll refactor this to use npm and Webpack to create a bundle that contains these libraries, so you won’t be relying on the CDN. But let’s get the search working first before adding additional complexity.

Create the file themes/basic/static/js/search.js and add an alert statement to the file so you can test that the script loads properly:

Save the file, and then switch back to themes/basic/layouts/_default/search.html and include the search.js file by adding this code after the other script tags:

Now, visit https://localhost:1313/search and you’ll see an alert box pop up. This demonstrates that your JavaScript is properly linked up.

Switch back to themes/basic/static/js/search.js. Remove the alert line from the file.

Define a global SearchApp object, which will hold some references you’ll need throughout the search script:

This stores references to the search field, search button, and the output area. It also defines two other properties: searchData and searchIndex.

You’ll fetch the JSON data from the server and store it in the searchData property. Then you’ll feed that to Lunr, which will build a search index that you’ll store in searchIndex. You’ll need to keep the original JSON data around because when you query the search index, the list of results won’t contain the title and other information in the search index. The results you’ll get contain the hyperlink to the page, along with other data like the relevance and weight. To display the page title, you’ll cross-reference the results you get with the original data.

Use the Axios library to fetch the data from the search page. When you get the results, store them in the searchData property. Then populate the search index with the results from the field:

Lunr uses the data from the title and the body to build the search index. When you perform a search, Lunr will compare the search terms with the words in its index and generate results.

Next, add an event listener to the search button which calls a search function, and then implement the function which uses Lunr to perform the search:

Lunr gives you results, but the results only contain a score and a hyperlink. To get results you can display, search through the JSON data you pulled from the server and match on the URLs. Then call the display function to display the results you found.

Finally, write the display function, which iterates over the results and displays them:

Take the search out for a spin. This current implementation only finds whole words, so search for “Jabberwocky” and you’ll see the link to that project appear in the results.

Let’s tweak the search to make it a little more useful.

Improving the Search

When you pass text to Lunr, it’s turning the text into a search query. When you pass single words, it searches for all documents containing that word. But if you search for multiple words, Lunr defaults to searching for documents that contain either word. So a search for “first post” would return all the documents with the word “first” or the word “post”.

If you wanted to show documents that contain all of the words, you’d have to place plus signs in front of each word. For example, to find pages with “first post”, you’d have to search for +first +post.

Finally, Lunr supports partial word search. You can use wildcard characters. Search for jabber* and you’ll get the result you’re looking for.

Your visitors won’t know about these search capabilities unless you add instructions to the site, so let’s modify the behavior of the search to make it easier for people to use. You’ll add asterisks to each word, and then add a checkbox that specifies that you’re looking for all words. If it’s checked, you’ll change the query yourself.

Add the wildcards first. Take the value you get from the search form, use the split() function to turn it into an array of words, use the map() function to transform each word and append the asterisk to each word, and then use join() to convert the result back to a string:

Save the file. Then try out the search in your browser by searching for Fir. The “First Post” entry displays.

When you use asterisks, Lunr will no longer find some complete words. If you search for “Jabberwocky” now, it won’t return any results because using wildcards disables Lunr’s stemming support. Stemming^[33] is the process of reducing a word to its stem. For example, if you have the words “building” or “builder”, the stem would be “build”. Lunr uses stemming to reduce the size of the index it builds. You can disable stemming support by removing it from the pipeline when you create the Lunr index:

Let’s add a checkbox to the form to allow users to require that all words are included in the search, instead of the default behavior. First, add a new checkbox field and corresponding label to the form. Open themes/basic/layouts/_default/search.html and add the new field:

Switch back to themes/basic/static/js/search.js and add a new field to the searchApp object that references the new checkbox:

Finally, in the search() function, right before you perform the search, check the checkbox. If it’s checked, prepend each word with a plus sign, using the same technique you used to append asterisks for the wildcards:

Save the file. Back in your browser, enter “first post” in the field, select the checkbox, and search. “First Post” is now the only result. Uncheck the box and you’ll get different results:

The order in which Lunr displays results is based on how many times the word appears in the document. When you perform the search, Lunr returns each result, along with a score. The more times a word appears, the higher the score. You can use these scores to set thresholds and tune your search even further.

Your Turn

Here are some additional things for you to explore to make your search more robust:

1. If you enter nothing in the search field, all the pages come back in the results. Modify the code to handle blank searches.

2. Some of the content of your pages is hidden in front matter. For example, your project pages contain technology used, which you might want to see in your searches. Explore how you can include this data in addition to the title and body content.

3. Review the Lunr documentation to explore how to create a serialized search index instead of creating one on the client. This will require additional processing when you publish your site, but it will speed things up substantially if you have a lot of content.

4. Explore other search options like Algolia and see how they stack up compared to Lunr.

Wrapping Up

You added a basic search to your site, using Hugo to generate a catalog of content, and JavaScript to download and search it. You refined the search to take advantage of some of Lunr’s features. In the next chapter, you’ll use Hugo’s asset management features to process your CSS and JavaScript files, getting things one step closer to production.

Chapter 7
Managing Assets with Pipes

A website is more than just its content. Stylesheets, images, and JavaScript bring a site to life, but managing these assets can be tricky.

When you’re getting your site ready for production, you’re looking for ways to make the experience better for your visitors. To improve speed, it’s common practice to process CSS and JavaScript files to minify them, which involves removing whitespace, line breaks, and comments to reduce the file size so the files transfer faster. It’s also common to fingerprint the CSS and JavaScript files so that they’ll have slightly different filenames when you deploy modified versions. This invalidates browser caches so visitors see your changes.

You might even want to take advantage of Sass, a CSS preprocessor that lets you break up your stylesheets, add logic, and create shared functionality. And now that you have a JS-powered search, you might want to create a bundle for your JavaScript files instead of relying on a version hosted by a CDN.

Hugo can handle all of this out of the box, thanks to its Pipes feature. Pipes let you transform your CSS and other assets right from within Hugo. You won’t need to install additional tooling to concatenate, minify, or fingerprint your files. As long as you’ve installed the extended version of Hugo, you’ve got everything you need.

Hugo also includes some powerful built-in features for managing images, including the ability to resize images automatically, or perform other forms of image processing, without the need for external tooling.

In this chapter, you’ll use Hugo’s built-in features to manage your CSS, images, and JavaScript files. You’ll also integrate Webpack^[34] into your project so that you can take advantage of advanced features Hugo doesn’t support, such as JavaScript modules. And since you’re going to do that integration, you’ll create some scripts to make building your project easier.

Managing Stylesheets

Right now you have a single CSS file for the site with a pretty minimalist design. As it grows, you may want to break it up into components, or evolve it further.

To use the pipelines feature of Hugo, you’ll need to move your CSS files out of the static directory and into a new assets directory.

Stop your Hugo server with Ctrl-c. Create a new directory in your theme named assets. You can do this with your editor, or with the following command:

Then move the static/css directory there:

Then in themes/basic/layouts/partials/head.html, locate the line of code that loads the stylesheet. Add this line above the stylesheet link to load the assets/css/style.css file:

The resources.Get function uses the assets directory as its base path. The contents of the file are read in to the $css variable.

To use the CSS file, modify the stylesheet link to use the $css variable:

The $css.RelPermalink piece writes the file to your site’s public/css/ directory and places the proper relative URL into the HTML document.

Start your server with hugo server and visit your home page again to ensure your styles still work.

Now that you’re pulling the CSS in with resources.Get, you can apply some transformations to the file.

Minifying and Fingerprinting Your CSS

It’s common practice to minify front-end content. This removes non-printable characters and comments, resulting in smaller files that transfer faster.

In addition, you can fingerprint your assets. When you serve up your stylesheet, your browser will cache it. When you update the page, your browser might not notice the changes unless you clear your local cache. One way to get around that is by using fingerprinting to create a unique filename for your CSS files that gets updated every time you make changes.

Hugo supports both minification and fingerprinting when you use the resources.Get function. You can pipe the resource to the minify and fingerprint functions. Modify the resources.Get line to do just that:

This results in a file with a name like /css/style.min.a939605b22...815d1.css". Its contents are minified, and the filename will change when you change the contents. Because Hugo is managing all of this, you don’t have to think about it.

Using Sass

Sass is a CSS preprocessor that offers advanced features. With Sass, you can break up your CSS into manageable chunks, define variables, and perform math. While some of these features are making their way into browsers, Sass is a popular choice for building front-end sites.

First, rename themes/basic/assets/css/style.css to themes/basic/assets/css.style.scss:

The scss syntax of Sass is a superset of CSS, so a CSS file is already a valid Sass file.

To use this file, update the filename and introduce the toCSS function into the pipeline, in front of the minify function:

This gets things working, and you can now integrate many of Sass’s features into your styles.

For a quick example, let’s extract the styles for the navbar into its own file so it’ll be easier to manage.

Create the file themes/basic/assets/css/_navbar.scss. The underscore denotes that this is a Sass partial which you can include into a main Sass stylesheet.

Switch to styles.scss and locate the styles related to the navigation bar:

Remember that one of the styles for the navigation bar is within a media query with some other styles:

Cut these style rules from the file and paste them into the _navbar.scss file. Create a new media query also. Your file will look like this when you’re done:

Then, back in the style.scss file, add an import statement, which will pull the _navbar.scss file’s contents into the main stylesheet when Hugo builds your site:

Save all of your changes. You now have a path forward to creating more complex and organized stylesheets for your site.

You haven’t done too much with images in this book yet, but that’s about to change. Hugo has some fantastic features for working with images that you’ll explore next.

Managing Images

Up until now, you’ve used placeholder images in your pages, but you’re going to want to place images in your blog posts, or screenshots of your projects. And you might even want an image on your home page. Hugo offers a few options for managing images: you can host images externally and link to them, you can place them in the static folder like you did with CSS files, or you can create a resource bundle and keep images with their associated content.

You already brought in images from an external site in Chapter 3, ​Adding Content Sections​. If your images are hosted elsewhere, you can use that same approach.

To link to images in the static folder of your theme or your site, use a standard <img> tag with a site-relative URL. This works in both your layouts and in your Markdown content.

Test this out by adding a local image to your site’s footer. In the companion files for this book, you’ll find an images directory. Copy the hugo-logo-wide.svg file from that directory to your site’s static directory. You could also place it in the static directory within your theme. Either way, you’ll access the file the same way, as the static directories are merged together.

With the file in place, open your theme’s footer partial at themes/basic/layouts/partials/footer.html and add the following code to include the image with a link to the official Hugo website:

Even though the image is located at /static/hugo-logo-wide.svg, you don’t specify the static part of the path to the file, as the contents of the static folder are copied to the root of the site. Using the relURL function ensures that the paths are generated relative to the page.

Save the file. When you load the page in your browser, the Hugo logo appears in the footer:

If you’re going to store more images in the static folder, you’ll probably want better organization. Create an images folder to store your images, and then include images in your image paths.

Images in the static folder are available in your content pages as well. When you’re working in Markdown documents, you include an image using Markdown’s image syntax like this:

However, if you’re going to include images in your Markdown content, Hugo has a better way, which will give you access to powerful functions to transform images: page bundles.

Using Page Bundles to Organize Content

Up until now, each piece of content you’ve created is a Markdown file with a name that somewhat resembles its title. But you can also create a page bundle, which is a collection of content files, including images, PDF files, or any other type of asset you want to keep close to your content. A page bundle is a folder inside of your content section, rather than an individual file.

To test this out, add a fourth blog post to your site. This post will contain a few images in addition to the text, and by using a page bundle, you’ll be able to keep those images in the same location as the text, making the content easier to organize.

Use the hugo new command to create the page bundle:

Notice that instead of calling the post my-vacation.md, you’re specifying my-vacation as part of the path, and specifying a file named index.md. Hugo creates the following structure:

This new my-vacation folder is where all of the assets associated with your post will go. Create a new images folder inside of this folder using your IDE or the following Terminal command:

In the companion files you downloaded for this book, you’ll find three photos in the images folder: badlands.jpg, rushmore.jpg, and bison.jpg. Copy all three of these photos to the content/posts/my-vacation/images folder.

Open portfolio/content/posts/my-vacation/index.md and add the following content: