Customize a Theme

The following are key concepts for Hugo site customization with themes. Hugo permits you to supplement or override any theme template or static file with files in your working directory.

Override Static Files

There are times where you want to include static assets that differ from versions of the same asset that ships with a theme.

For example, a theme may use jQuery 1.8 in the following location:

/themes/<THEME>/static/js/jquery.min.js

You want to replace the version of jQuery that ships with the theme with the newer jquery-3.1.1.js. The easiest way to do this is to replace the file with a file of the same name in the same relative path in your project’s root. Therefore, change jquery-3.1.1.js to jquery.min.js so that it is identical to the theme’s version and place the file here:

/static/js/jquery.min.js

Override Template Files

Anytime Hugo looks for a matching template, it will first check the working directory before looking in the theme directory. If you would like to modify a template, simply create that template in your local layouts directory.

The template lookup order explains the rules Hugo uses to determine which template to use for a given piece of content. Read and understand these rules carefully.

This is especially helpful when the theme creator used partial templates. These partial templates are perfect for easy injection into the theme with minimal maintenance to ensure future compatibility.

For example:

/themes/<THEME>/layouts/_default/single.html

Would be overwritten by

/layouts/_default/single.html

Override Archetypes

If the archetype that ships with the theme for a given content type (or all content types) doesn’t fit with how you are using the theme, feel free to copy it to your /archetypes directory and make modifications as you see fit.