How to streamline theme switching in Hugo

blogging
Published

June 24, 2025

After nearly 3 years using the PaperMod theme for my blog built on Hugo, I’ve decided to switch to another theme that can serve my current need better. This blog post will discuss the steps I took.

Why switch?

Blogging on technical topics, especially those involving multiple components, usually results in longer-form content. The native support for TOC in PaperMod is disappointing as it is only displayed on top of the page. Readers will easily lose the content structure when they burrow deeper. Having a TOC by the side that floats along your reading will serve this purpose much better.

I also find the tags and category in PaperMod somewhat overlapping. What I want are high level clusters that group related posts together and offer a single, clean place to organize my posts.

My requirements

Context-aware TOC

As my primary goal for this switch, I am looking for themes with support for floating, context-aware TOC in blog posts. This is always available for documentation themes like these:

  • Hugo-book: simple, dark mode, no title page, minimal blog support.
  • Eureka: elegant, dark mode, nice title page with ability to add about page, no blog support
  • Doks: modern landing page with separate docs and blog section. Unfortunately the blog section has no TOC.
  • Lotus Docs: highly functional doc template with no blog.

My usage scenario requires a mix of content from blogs, projects and a personal profile. My blog content spans different domains of varied length, that can be categorized in multiple ways. Thus the structural layout of the above doc themes (which are built more like a book with fixed chapters) do not suit me. Hence I’m moving back to searching for blog-centric theme that must have a floating side TOC. The followings are my findings along with my thoughts on each of them.

  • Stack: the 3 columns setting seem a bit cramped. Posts are arranged like cards. TOC doesn’t change color with context too. However, different levels of paragraphs are visually distinct. Also useful for building image galleries. This is a very strong candidate if not for the 3-column layout.
  • Poison: just like Stack, I’m just not a big fan of 3-column layouts.
  • Cleanwhite: clean and simple, but lacking a separate home page. I would imagine this be a great feed for a pure blog author.
  • Gokarna: has a simple but adequate home page with posts and pages in dark mode. Floating TOC is context aware with nice to parse colors.
  • CodeIT has everything I want, but it is not maintained anymore.
  • Fixes to Papermod to include floating side TOC
  • customize existing CSS and HTML files for any Hugo site.
  • al-folio: Jekyll theme which requires more setup time due to platform change.
  • Chirpy: Jekyll theme. 3 column layout. I really love the floating TOC’s implementation, which expand and collapse sections per context. This reduces clutter on the screen and make the reading experience cleaner and lighter.

Aesthetics

  • minimal and bright: even though I really love the simple approach of Codexand Winston themes, the lack of side TOC kills them for me.
  • dark mode to reduce eye strain.

Misc.

  • title card: a homepage with my basic information, acting as an orientation page for my blog, resume, social links, etc.
  • flexible support for analytics software of my choice.

Steps I took

My final pick is Gokarna due to its simple homepage, and native support for floating TOCs. I also like that the main column has more efficient utilization of screen real estate, as compared with the single column layout of PaperMod.

The following sections will outline the steps I take to migrate my existing PaperMod site to Gokarna.

Creating or moving to a new site always involves examining the new theme’s structure via its exampleSite content, the config.toml file, and any instruction provided in its github repo readme file.

Two specific places are

  • site config file: hugo.toml or config.yml. This controls the look and information architecture of the site.
  • content in the exampleSite\content folder. This shows the content architecture of the site, with different folders for blog posts, about page for personal profile, project pages, and misc. supporting content that can populate the homepage. Study it carefullly as each theme differs.

Configure global site settings

The first step is to create a clear mapping of how our old configuration file’s keys/values map to the new theme.

  1. Create a new hugo site called NewBlog.

  2. Clone the Gokarna theme as a submodule per instruction.

  3. Copy the hugo.toml in themes\gokarna\exampleSites to our NewBlog root folder.

  4. In our code editor, open Gokarna’s hugo.toml side by side with our existing config.yml from PaperMod.

  5. Follow the instruction to configure our new site in hugo.toml. For me it involves the following steps:

    1. change baseURLto our custom domain

    2. change title.

    3. in [params] section

      • change the avatar to our own image.
      • optionally, change accentColor to something that matches our avatar color palette by using a color picker tool. This will only change hover color for hyperlinks in a page. It will not affect top level menu items or TOC. To make a global change, make sure to copy the layouts\partials\head.html file from the theme folder to our root folder, and change the default HEX value to match.
      :root {
    --accent-color: {{ .Site.Params.AccentColor | default "#FF4D4D" }};
      • setup socialIcons for our social links on the home page.
      • Unlike PaperMod, there is no native Google Analytics support. Instead, we can take advantage of custom head element to insert whatever analytics script we use. This is more flexible than PaperMod. For example, we can setup Google Analytics this way in [params]
      customHeadHTML = """
<script async src="https://www.googletagmanager.com/gtag/js?id=G-XXXXXXXX"></script>
"""
      • Instead of just an avatar and social links, we can also choose to add some blog posts to the home page.

    4. reconfigure the [menu] section to setup the upper right menu items. A nice touch is the use of feather icons in the menu items.

    5. Enable Table of Content with this new section:

    [markup]
  [markup.tableOfContents]
  startLevel = 1
  endLevel = 4
  ordered = false
    1. Enable automatic generation of sitemap with this new section:
    [sitemap]  
changeFreq = "weekly"  
filename = "sitemap.xml"   
priority = -1  # Default priority (-1 means omitted from rendered sitemap)

    Then, go to the layouts/_default/ folder and add a new file called sitemap.xml. This will be a template file to generate a sitemap for our site. Paste the content from the official Hugo github repo. We can also refer to this and this post to customize what content to exclude.

Convert content files

Now we are ready for action! We will convert all our existing content over.

  1. Start by moving all our existing blog posts from the content\posts folder over to our new site.
  2. Check if any supporting content in exampleSite\content\ are applicable. These might include projects, data and other profile pages that we can build new content from.
  3. The major conversion happens in the frontmatter of each existing blog post (i.e., all the index.md files). As PaperMod and Gokarna uses different fields in the yaml frontmatter, we need to convert them to ensure the right fields are properly setup and old/irrelevant fields are removed. We also need to setup new fields Gokarna needs.

I whip up the following Python script to automatically parse all the index.md files in each posts subfolders. Make sure to change root_dir to point to the new site’s posts folder.

import os
import re
import yaml

# Set the root directory to begin the walk  
root_dir = r"\path\to\newBlog\content\posts"

# A regex to capture the YAML front matter (delimited by "---")
# and separate out the markdown body.
yaml_regex = re.compile(r"^---\s*\n(.*?)\n---\s*\n(.*)$", re.DOTALL)

for dirpath, dirnames, filenames in os.walk(root_dir):
    if "index.md" in filenames:
        filepath = os.path.join(dirpath, "index.md")
        print(f"Processing {filepath}...")
        with open(filepath, "r", encoding="utf-8") as f:
            content = f.read()

        match = yaml_regex.match(content)
        if not match:
            print(f"  Skipping {filepath}: No valid YAML front matter detected.")
            continue

        yaml_content, body = match.groups()

        # Parse the YAML front matter into a dictionary.
        try:
            data = yaml.safe_load(yaml_content)
        except Exception as e:
            print(f"  Error parsing YAML in {filepath}: {e}")
            continue

        # Prepare new YAML front matter lines.
        new_lines = []
        new_lines.append("---")

        # Title
        if "title" in data:
            # Ensure the title is wrapped in double quotes.
            new_lines.append(f'title: "{data["title"]}"')

        # Date
        if "date" in data:
            new_lines.append(f'date: "{data["date"]}"')
            # Set #lastmod equal to the date – note the comment prefix.
            new_lines.append(f'#lastmod: "{data["date"]}"')

        # Draft
        if "draft" in data:
            new_lines.append(f'draft: {str(data["draft"]).lower()}')

        # Description
        if "description" in data:
            new_lines.append(f'description: "{data["description"]}"')

        # Image: get from cover.image if available.
        cover_image = ""
        if "cover" in data and isinstance(data["cover"], dict):
            cover_image = data["cover"].get("image", "")
        new_lines.append(f'image: "{cover_image}"')

        # Set type to post.
        new_lines.append('type: "post"')

        # Convert showToc to showTableOfContents.
        # If showToc exists and is truthy, set to true; otherwise false.
        show_toc_val = "true" if data.get("showToc", False) else "false"
        new_lines.append(f'showTableOfContents: {show_toc_val}')

        # Preserve the commented "# weight:" line if present in original YAML.
        weight_line = None
        for line in yaml_content.splitlines():
            if line.strip().startswith("# weight:"):
                weight_line = line.strip()  # keep the formatting as-is
                break
        if weight_line:
            new_lines.append(weight_line)

        # For tags, use values from the categories field.
        tags_list = data.get("categories", [])
        # Make sure each tag is converted to a string and wrapped in double quotes.
        formatted_tags = ", ".join(f'"{str(tag)}"' for tag in tags_list)
        new_lines.append(f'categories: [{formatted_tags}]')

        new_lines.append("---")
        new_yaml = "\n".join(new_lines)

        # Write the new YAML front matter and append the remaining markdown body.
        new_content = new_yaml + "\n" + body
        with open(filepath, "w", encoding="utf-8") as f:
            f.write(new_content)

print("Processing complete.")

Finally, run hugo server in our site’s root folder to do a sanity check of everything before pushing it live.

Conclusion

In this post, I described the theme hunting process (and candidates) for a new Hugo theme that supports context-aware TOC while providing a clean homepage for personal profile. This turned out to be the most time-consuming tasks as I needed to go to multiple theme portal sites and visually inspect the demo sites of each potential theme. I also went over the process of migrating an existing site configuration to the new theme, and moving all the blog posts over programmatically with a Python script to convert each file’s yaml frontmatter. Doing it in Python saves a lot of time especially if you have a sizeable chunk of content.

I would like to thank adityatelange for the PaperMod theme. It’s rock solid with a lot of features that I will miss (e.g., an Archives page breaking down posts into year/month, 3 types of homepages, Search, cover image for each post, share buttons, code copy button)!

That said, needs change and it’s always good to have more suitable options for our current situation. I’m grateful for the Hugo ecosystem with its good community support and a diverse choice of themes for different needs.

Back to top