Skip to main content
LaRomierre
A laptop screen displays a blog homepage with an article titled 'Customizing Hugo Theme Stack'. Below the article summary, several colorful keyword tags such as 'HUGO' and 'THEME DEV' are visible. The laptop rests on a dark desk mat next to a mechanical keyboard and a cup of coffee.

Customizing Hugo Theme Stack: Adding Tags to the Homepage

• 3 min • 622 words
Hugo Hugo-theme-stack Web-Development Frontend Go-Templates Customization

In this guide, I will walk you through how to update the Hugo Theme Stack to display article tags directly on the homepage. I will also show you how to add configuration options to control this display globally (site-wide) and locally (per article).

Prerequisites

I assume you already have a Hugo website up and running, and that you are using a theme you can modify (likely forked from the official Hugo Themes).

If you are just starting, I recommend reading my previous guide on jumpstarting a Hugo website before continuing.

Note: This tutorial is based on the Stack theme by Jimmy Cai. If you are using a different theme, the logic remains similar, but the specific filenames and structure may vary.

Important: Never modify files directly inside the themes/ folder. Instead, mirror the file structure in your project’s root layouts/ directory. Hugo will automatically prioritize your root files over the theme’s files.

The Goal: Why Display Tags?

Hugo uses the concept of taxonomies. By default, it offers “Categories” and “Tags.” You define these in your article’s frontmatter like this:

+++
...
categories = ["Tech"]
tags = ["Hugo", "Hugo Themes", "Web Design", "Frontend", "GoHugo", "Customization"]
...
+++

With the Stack theme, tags are typically displayed in two locations:

  1. At the bottom of the article page (before the footer).

  2. In the right sidebar widget on the homepage (if enabled).

List of tags in the footer of articles
List of tags in the footer of articles

However, displaying tags directly on the article card on the homepage is incredibly useful for readers. Combined with the title and description, tags give immediate context about the topics explored in the post without needing to click through.

Step 1: Locating the Layout Files

First, let’s examine layouts/partials/article-list/default.html. This partial controls how articles are displayed in the homepage list. It invokes another partial: layouts/partials/article/components/headers.html.

Currently, the homepage and the article detail page share this same header structure: cover image, title, description, category, date, and reading time. We want to diverge here by adding a tags element only for the homepage.

I explored a few approaches to achieve this:

  1. Context Passing: Modify the call in default.html to pass a variable like (dict "context" . "isHome" true). This requires extensive modification of headers.html and details.html to handle the dictionary context. (See this discussion for details).

  2. File Duplication (Recommended): Create a specific header file for the homepage.

I chose the second solution. It is cleaner and safer if you plan to make further homepage-specific customizations later (like changing how the date is displayed).

Step 2: Creating the Homepage Block

  1. Create a copy of header.html and name it home-article-block.html.

  2. In default.html, update the code to reference this new file:

{{ $image := partialCached "helper/image" (dict "Context" . "Type" "articleList") .RelPermalink "articleList" }}
<article class="{{ if $image.exists }}has-image{{ end }}">
    {{ partial "article/components/home-article-block" . }}
</article>
  1. Open home-article-block.html. We need to insert the logic to display tags. Place the following block right after the <div> containing the description:
...
    {{ with .Params.description }}
        <h3 class="article-subtitle">
            {{ . }}
        </h3>
    {{ end }}
</div>

{{ if .Params.Tags }}
    {{ $tags := .GetTerms "tags" }}
    {{ range $index, $tag := $tags }}
        <a href="{{ $tag.RelPermalink }}">{{- $tag.LinkTitle -}}</a>
    {{ end }}
{{ end }}
...

Now, if you run hugo server, articles with tags will display them on the homepage.

Step 3: Global & Local Configuration

Hardcoding this feature isn’t ideal. Let’s add a configuration switch to enable or disable this globally, with the ability to override it per article.

Global Configuration (config.yaml)

Add a default parameter to your site configuration:

params:
  ...
  showHomepageTags: true

Local Override (Frontmatter)

You can now override this in a specific article’s frontmatter. For example, to hide tags for a specific post:

+++
showHomepageTags = false
+++

Implementing the Logic

Update your home-article-block.html to respect these settings:

...
{{ $showHomepageTags := .Params.showHomepageTags | default (.Site.Params.showHomepageTags) }}
{{ if and $showHomepageTags .Params.Tags }}
    {{ $tags := .GetTerms "tags" }}
    {{ range $tag := $tags }}
        <a href="{{ $tag.RelPermalink }}">{{- $tag.LinkTitle -}}</a>
    {{ end }}
{{ end }}
...

Step 4: Styling and Icons

Let’s make it look consistent with the theme’s design.

1. Add CSS: In assets/scss/partials/article.scss, add:

.home-article-tags {
  font-weight: lighter;
  color: var(--home-article-tags-color);
  line-height: 1.2;
  font-size: 1.5rem;

  hr {
    border: none;
    height: 0.5px;
    width: 100%;
    background-color: var(--home-article-tags-hr-color);
    margin: 5px 0;
  }
}

2. Define Colors: In variables.scss, define the CSS variables for both light and dark modes:

:root {
  --home-article-tags-color: rgba(114, 114, 114, 1);
  --home-article-tags-hr-color: rgba(153, 153, 153, 1);

  &[data-scheme="dark"] {
    --home-article-tags-hr-color: rgba(102, 102, 102, 1);
    --home-article-tags-color: rgba(255, 255, 255, 0.7);
  }
}

3. Add an Icon: Create assets/icons/tags.svg and paste the SVG code (e.g., from Tabler Icons).

4. Final Assembly: Update home-article-block.html to include the structure, icon, and separators:

{{ if and $showHomepageTags .Params.Tags }}
    <section class="home-article-tags">
        <hr>
        {{ partial "helper/icon" "tags" }}
        {{ $tags := .GetTerms "tags" }}
        {{ range $index, $tag := $tags }}
            {{ if $index }}, {{ end }}
            <a href="{{ $tag.RelPermalink }}">{{- $tag.LinkTitle -}}</a>
        {{ end }}
        <hr>
    </section>
{{ end }}

Wrap up

You now have a clean, configurable way to display tags on your homepage using the Stack theme.

If you want to see the final result in action or check the source code directly:

Happy coding!