Customize a Hugo theme

Add a feature to an existing Hugo theme without forking it or breaking future updates.

Customizing a Hugo theme without forking it is a solved problem — but the moving parts (partials, lookup order, layouts/ overrides) trip up almost everyone. Hugo Chat handles the lookup logic for you so you can focus on the change you actually want to make.

The override pattern

Hugo themes ship templates in themes/<name>/layouts/. Your site can override any of them by placing a file with the same path in layouts/ at the project root. Hugo's lookup order picks your version first.

This means you almost never need to fork the theme. You override the bits you want and leave everything else upstream.

Walkthrough — adding a custom homepage section

Say you're using a theme and you want to add a "Featured projects" section to the homepage between the hero and the recent posts.

1. Find the file to override

Ask Hugo Chat:

@your-name/your-blog where is the homepage layout, and what partials does it call?

Hugo Chat will list the file (often layouts/index.html in the theme) and the partials it pulls in.

2. Mirror the path in your project

Create the same file path locally — for example layouts/index.html. Hugo will use this instead of the theme's version.

3. Insert your section

Ask Hugo Chat to write the section:

Add a "Featured projects" section after the hero. Pull from a
content/projects/ folder, show the 3 most recent projects with
title, description and cover image, in a 3-column grid that
collapses to 1 column on mobile.

You'll get the partial, the section markup, and the CSS — matched to the theme's existing styles.

4. Verify locally

Run hugo server and check the homepage. If something's off, paste the visual problem back to Hugo Chat with the file:

The cards are touching the hero on mobile. Add 4rem of top padding
on screens under 768px.

What this gets you

Updates still work. Pull theme updates without merge conflicts — your overrides live in your project, not the theme.
Repeatable. The same pattern works for headers, footers, post layouts, taxonomy pages, anything.
Reviewable. Your customizations are a clean, small set of files in layouts/ — easy to read and roll back.

When to fork instead

Override-by-path stops being practical when you're rewriting more than ~30% of a theme. At that point, fork it. Hugo Chat can help with the fork too — ask it to scaffold a fresh theme based on the structure of the one you were customizing.

On this page