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!
— Yihui, Amber, & Alison
In Hugo, themes control the entire appearance and functionality of your site. A Hugo theme is made with the following elements:
Configuration files. This may be a single
config.tomlfile in the root of your website project. Some themes also use a configuration directory, located in
config/_default/. Read more about these files in Chapter 2.2.
Layout files, located for example in
themes/hugo-lithium/layouts/. Hugo is a templating system, so layout files are
*.htmlfiles, with a specific file and naming structure. Read more about these files in Section 2.5.
Style asset files like fonts and CSS.
All of these files are contained in the
themes/ folder, and are kept separate from your website
content/. However, all Hugo themes rely on specific
content/ and YAML frontmatter, so do not be fooled into thinking that themes and content are not dependent on each other—they are! In this section, we provide some opinionated advice on choosing themes, as well as recommended workflows for working with Hugo themes using blogdown.
If you care a lot about the appearance of your website, you will probably spend quite a bit of time in the beginning looking for a Hugo theme that you like from the collection listed at https://themes.gohugo.io. Please note that not all themes have been tested with blogdown. If you find a certain theme does not work well with blogdown, you may report to https://github.com/rstudio/blogdown/issues, and we will try to investigate the reason, but it can be time-consuming to learn and understand how a new theme works, so we recommend that you learn more about Hugo by yourself before asking, and we also encourage users to help each other there.
There are now about 400 Hugo themes to choose from. To save you some time, we list a few themes below that match our taste:
Multimedia content themes: If you are interested in adding multimedia content to your site (such as audio files of a podcast), the castanet theme provides an excellent framework tailored for this application. An example of a site using blogdown with the castanet theme is the R-Podcast.
Another thing to keep in mind is that the more effort you make in a complicated theme, the more difficult it is to switch to other themes in the future, because you may have customized a lot of things that are not straightforward to port to another theme. So please ask yourself seriously, “Do I like this fancy theme so much that I will definitely not change it in the next couple of years?”
If you choose to dig a rather deep hole, someday you will have no choice but keep on digging, even with tears.
— Liyun Chen13
To use a Hugo theme other than
hugo-lithium with a new site (which we showed in Section 1.2), we recommend the following workflow:
Carefully pick a theme at https://themes.gohugo.io, and find the link to its GitHub repository,14 which is of the form
https://github.com/user/repo. For example, the source of the Hugo theme Anatole is located at https://github.com/lxndrblz/anatole.
In the “Hugo theme” field, enter the
user/repofrom the link in Step 1. Click “Create Project.”
Alternatively, in the R console, you may type
blogdown::new_site(theme = 'user/repo'):
# for example, create a new site with the anatole # theme ::new_site(theme = "lxndrblz/anatole")blogdown
Play with the new site for a while and if you do not like it, you can repeat the above steps, otherwise edit the options in the configuration file (
config.toml). If you do not understand certain options, go to the documentation of the theme, which is often the README page of the GitHub repository. Not all options have to be changed.
Generally, we do not advise you to switch themes, as each Hugo theme depends on different variables that you provide in the theme-specific configuration file (
config.toml) and in the YAML of the
content/ files. Example sites are often provided for individual themes, so we recommend using
blogdown::new_site(), then editing the provided example site as a starting point. However, if you do want to test a different Hugo theme with an existing site, you can start with the following workflow:
In the R console, install the theme via
::install_theme(theme = "lxndrblz/anatole")blogdown
Manually move the configuration file (
config.toml) from the
themes/theme-name/exampleSite/directory to the root directory of your website to match the newly installed theme.
Carefully inspect the differences between your new theme’s
exampleSiteand the files inside your
content/folder. A theme’s
exampleSitecontent is tailored to a specific theme, so changing themes without changing your
content/is a bit like wearing someone else’s clothes—they just may not fit right.
Updating Hugo theme files is not for the faint of heart, and we also do not recommend doing this unless you must. We also generally recommend you only do this when you integrate GIT and GitHub for version control, and that you attempt to update your theme in a branch first.
The main reason this is difficult is that Hugo theme files can require changes in your website configuration file (
config.toml) and in the YAML of individual content files, depending on the extent of the theme update. So updating a theme can be quite a hassle.
Why do theme developers update their themes? Three reasons. One, Hugo changes. As a result, Hugo theme developers must change their themes to keep up with deprecated Hugo functions. Two, Hugo theme developers fix their themes when bugs are reported. Three, popular Hugo themes often field lots of feature requests, and some theme developers are responsive to adding new features.
If you find yourself needing to update your theme, you may do the following:
::install_theme(theme = "lxndrblz/anatole", force = TRUE)blogdown
Then slowly work through what changed in the site configuration files and the
content/ frontmatter (YAML metadata) by comparing the updated theme’s
exampleSite. As stated earlier, we recommend doing this work in a different branch (i.e., not
main) before merging.