Hugo is a powerful static site generator that allows developers and content creators to quickly build fast and scalable websites. One of the core features of Hugo is its templating system, which helps in structuring the content and customizing the look and feel of the site. If you are new to Hugo or want to leverage its templating capabilities more effectively, this step-by-step guide will show you how to use templates built into Hugo.

What Are Templates in Hugo?

Templates in Hugo are files that define how the content on your site will be rendered. They are made up of HTML, CSS, and Hugo-specific code, allowing you to customize the layout of your website. Templates can be used for various purposes, such as creating headers, footers, single pages, lists, and more.

Understanding the Issue Checkbox Not Showing

Hugo has built-in templates that are part of its theme structure, and it also allows you to create custom templates for greater flexibility. These templates are applied automatically based on content type, URL structure, and other variables, making it easier to manage complex sites.

Step 1: Install Hugo and Create a New Site

Before diving into templates, you first need to install Hugo and set up your site. Here’s how you do that:

  1. Install Hugo:
    • If you haven’t installed Hugo, follow the official installation guide for your operating system: Installing Hugo.
  2. Create a New Hugo Site:
    • Run the following command in your terminal to create a new site: 
      hugo new site mysite
    • This will create a new directory called mysite with the basic file structure for your Hugo project.

Step 2: Add a Theme

Hugo works with themes to manage how content is displayed. You can either use an existing theme from Hugo Themes or create a custom one. For simplicity, let’s use a theme from the Hugo themes library.

  1. Add a Theme:
    • You can add a theme by cloning it into your themes/ directory. For example, let’s use the “Ananke” theme: 
      git init
git submodule add https://github.com/budparr/gohugo-theme-ananke.git themes/ananke
  2. Configure the Theme:
    • Open your config.toml file and set the theme: 
      theme = "ananke"

Step 3: Understand Hugo Template Structure

Hugo’s templating system is based on the Go templating language. The templates are divided into several categories based on their purpose:

  • Base Templates: These are the overarching templates that wrap the content. They often include common sections like headers, footers, and navigation.
  • Content Templates: These define how individual content types (e.g., blog posts, pages, sections) are displayed.
  • List Templates: These templates control how groups of content are presented (e.g., a list of blog posts).
  • Partial Templates: These are smaller reusable snippets (e.g., navigation bar or footer) that are included in the main templates.

Common Template Directories

  • layouts/: Contains all the layout files like index.html, single.html, etc.
  • themes/: Contains templates that come with your chosen theme.
  • content/: Stores your content files (usually written in Markdown).

Step 4: Create a Template

Let’s explore how to create and modify a template for a page.

  1. Create a New Content File:
    • To create a new page (e.g., a blog post), use the following command: 
      hugo new posts/my-first-post.md
    • This creates a new Markdown file inside content/posts/ with front matter (YAML or TOML) and a placeholder for your content.
  2. Create a Template for Single Pages:
    • In the layouts directory, create a file named single.html inside layouts/_default/. This will control how individual content pages are displayed. 
      <!-- layouts/_default/single.html -->
<html>
<head>
    <title>{{ .Title }}</title>
</head>
<body>
    <header>
        <h1>{{ .Title }}</h1>
    </header>
    <main>
        <article>
            {{ .Content }}
        </article>
    </main>
</body>
</html>
    • This template will display the title and content of any single page you create.
  3. Create a List Template:
    • Similarly, you can create a list template for displaying multiple content items (e.g., a list of posts). Create a list.html in the layouts/_default/ directory. 
      <!-- layouts/_default/list.html -->
<html>
<head>
    <title>{{ .Title }}</title>
</head>
<body>
    <header>
        <h1>{{ .Title }}</h1>
    </header>
    <main>
        <ul>
        {{ range .Pages }}
            <li><a href="{{ .Permalink }}">{{ .Title }}</a></li>
        {{ end }}
        </ul>
    </main>
</body>
</html>

Step 5: Customizing Templates

You can enhance your templates with Hugo’s rich set of templating functions. For example, you can include custom CSS, loop over variables, or format dates:

  • Adding CSS: You can link a CSS file to your template: 
    <link rel="stylesheet" href="{{ "styles.css" | relURL }}">
  • Format Dates: Use the date function to display dates in a specific format: 
    <p>Published on: {{ .Date.Format "January 2, 2006" }}</p>

Step 6: Serve and Preview Your Site

Once your templates are in place and you’ve added content, you can preview your site locally:

hugo server

Navigate to http://localhost:1313 to view your site.

FAQ about Hugo Templates

1. What is the purpose of the “layouts” directory in Hugo?

The layouts directory is where you store all your template files in Hugo. It is used to define how different types of content (e.g., posts, pages, lists) will be rendered on the front end of your site. The templates are organized by type and location, such as single.html for individual content pages and list.html for content lists.

2. Can I create my own custom templates in Hugo?

Yes, you can create custom templates in Hugo. By placing your templates in the layouts directory, you can create specialized templates for specific content types, sections, or even unique content displays. Hugo also allows you to override default templates from your chosen theme.

3. How does Hugo handle content files and templates?

Hugo uses a system where content files (written in Markdown or other formats) are paired with templates to define how they are displayed. When you create content (e.g., a blog post), Hugo automatically looks for an appropriate template (e.g., single.html) and renders the content using that template. Hugo also supports content organization into sections, which can use different templates.

4. What are partial templates in Hugo?

Partial templates are reusable components or snippets of HTML that can be included in other templates. For example, a header, footer, or navigation menu can be created as partials and included in various templates using the {{ partial "header.html" . }} syntax. This helps in maintaining DRY (Don’t Repeat Yourself) principles and makes the site easier to manage.

5. Can I use Hugo templates with a custom theme?

Yes, you can use custom themes in Hugo. You can either create your own theme or use an existing one from the Hugo theme repository. If you’re using an existing theme, you can override its templates by adding your custom templates in the layouts directory, which allows you to modify specific parts of the theme without changing the entire structure.

By following these steps and understanding Hugo’s templating system, you can build powerful, customizable websites. Whether you’re using built-in templates or creating your own, Hugo provides the flexibility and speed needed to develop static sites with ease.