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
layouts/partials/ in the theme. The former will be added inside
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
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.↩︎