Customizing the Terio Theme for Hugo: Troubleshooting Guide

Why I Choose Hugo

I use Hugo as my blogging platform of choice for several compelling reasons:

• It’s opensource, giving complete control over the codebase
• Compilation and live preview are lightning-fast
• Hosting options range from free to very affordable
• The architecture maintains relative simplicity

The main challenge? Debugging can be surprisingly complex, especially when customizing themes.

The Terio Theme: Features and Challenges

For my website manuellevi.ai, I selected the Terio theme. It offers a robust feature set:

• Built-in search functionality
• RSS feed integration
• Modern Bootstrap 5.x foundation
• Fully responsive design
• Comprehensive page templates beyond basic blogging

While Terio provides excellent functionality, I’ve encountered several issues requiring direct intervention. This guide shares the solutions I’ve developed through collaboration with the theme developers.

Essential Fixes for Common Issues

1. Fix The Search Functionality

A common issue after deployment is non-functioning search - the search bar appears but yields no results. Here’s the fix:

Navigate to themes/terio/layouts/partials/scripts.html and remove these conditional lines: {{ if .Site.Params.sidebar.search }} and its closing {{ end }}, as shown here:

2. Fix Broken Footer Links

Dead footer links are another frequent issue. Here’s a two-step solution:

1. First, modify /themes/terio/layouts/partials/footer.html:
   • Locate <p>{{ .Title }}</p>
   • Replace with <p><a href="{{ .Permalink }}">{{ .Title }}</a></p>

2. Then update the styling in /themes/terio/assets/scss/_basic.scss:

Find this block around line 628:

.latest-news p {
    color: #999;
}

Replace with this enhanced version:

.latest-news p,
.latest-news p a {
    color: #999;
}
.latest-news p a:hover {
    color: #fff;
}

3. Make Search Work With All Pages

By default, Terio’s search only indexes blog posts. For sites with services, portfolios, or other content types, you’ll want to expand this functionality.

The search system relies on cmod/hugofastsearch which generated an index.json. It’s template can be found at /themes/terio/layouts/_default/index.json

To enable site-wide search, modify:

• /themes/terio/layouts/_default/index.json
• /themes/terio/static/plugins/search/simple-search.js

The guys behind Terio support theme told me this was considered custom development and was not included in the standard support. If you’re interested in doing this yourself, just send me a message on LinkedIn and I’ll send you the code.

4. Removing the Preloader Animation

For a faster initial page load, and much faster live feedback, you can disable the preloader:

1. Open /themes/terio/layouts/_default/baseof.html
2. Remove line 6: {{ partial "preloader.html" . }} or comment it out with {{/* partial "preloader.html" . */}}

That’s all it takes to eliminate the loading animation.