A note from the authors: Some of the information and instructions in this book are now out of date because of changes to Hugo and the blogdown package. If you have suggestions for improving this book, please file an issue in our GitHub repository. Thanks for your patience while we work to update the book, and please stay tuned for the revised version!

In the meantime, you can find an introduction to the changes and new features in the v1.0 release blog post and this "Up & running with blogdown in 2021" blog post.

— Yihui, Amber, & Alison

2.6 Custom layouts

It is very likely that you want to customize a theme unless you designed it. The most straightforward way is to simply make changes directly in the theme,22 but the problem is that a Hugo theme may be constantly updated by its original author for improvements or bug fixes. Similar to the “you break it, you buy it” policy (the Pottery Barn rule), once you touch someone else’s source code, you will be responsible for its future maintenance, and the original author should not be responsible for the changes you made on your side. That means it may not be easy to pull future updates of this theme to your website (you have to carefully read the changes and make sure they do not conflict with your changes), but if you are completely satisfied with the current state of the theme and do not want future updates, it is fine to modify the theme files directly.

A theme author who is aware of the fact that users may customize their theme will typically provide two ways: one is to provide options in config.toml, so that you can change these options without touching the template files; the other is to leave a few lightweight template files under layouts/ in the theme, so that you can override them without touching the core template files. Take the XMin theme for example:

I have two empty HTML files head_custom.html and foot_custom.html under layouts/partials/ in the theme. The former will be added inside <head></head> of a page, e.g., you can load JavaScript libraries or include CSS style sheets via <link>. The latter will be added before the footer of a page, e.g., you may load additional JavaScript libraries or embed Disqus comments there.

The way that you customize these two files is not to edit them directly in the theme folder, but to create a directory layouts/partials/ under the root directory of your website, e.g., your directory structure may look like this:

your-website/
├── config.toml
├── ...
├── themes/
│   └── hugo-xmin/
│       ├── ...
│       └── layouts/
│           ├── ...
│           └── partials
│               ├── foot_custom.html
│               ├── footer.html
│               ├── head_custom.html
│               └── header.html
└── layouts
    └── partials
        ├── foot_custom.html
        └── head_custom.html

All files under layouts/ under the root directory will override files with the same relative paths under themes/hugo-xmin/layouts/, e.g., the file layouts/partials/foot_custom.html, when provided, will override themes/hugo-xmin/layouts/partials/foot_custom.html. That means you only need to create and maintain at most two files under layouts/ instead of maintaining all files under themes/. Note that this overriding mechanism applies to all files under layouts/, and is not limited to the partials/ directory. It also applies to any Hugo theme that you actually use for your website, and is not limited to hugo-xmin.

  1. If you are new to web development, be careful changing content within the theme. Minor changes like colors and font sizes can be found within the CSS files of the theme and can be altered simply with minimal risk of breaking the theme’s functionality.↩︎