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

1.7 Other themes

In Hugo, themes control the entire appearance and functionality of your site. A Hugo theme is made with the following elements:

  1. Configuration files. This may be a single config.yaml or config.toml file 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.

  2. Layout files, located for example in themes/hugo-lithium/layouts/. Hugo is a templating system, so layout files are *.html files, with a specific file and naming structure. Read more about these files in Section 2.5.

  3. Style asset files like fonts and CSS.

  4. HTML dependencies like JavaScript files.

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.

1.7.1 Choosing themes

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:

If you do not understand HTML, CSS, or JavaScript, and have no experience with Hugo themes or templates, it may take you about 10 minutes to get started with your new website, since you have to accept everything you are given (such as the default theme); if you do have the knowledge and experience (and desire to highly customize your site), it may take you several days to get started. Hugo is really powerful. Be cautious with power.

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 Chen12

1.7.2 New site, new theme

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:

  1. Carefully pick a theme at https://themes.gohugo.io, and find the link to its GitHub repository,13 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.

  2. Create a new project in RStudio (File -> New Project -> New Directory -> Website using blogdown) (see Figures 1.1 and 1.2).

  3. In the “Hugo theme” field, enter the user/repo from 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
blogdown::new_site(theme = "lxndrblz/anatole")

  4. 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.yaml or 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.

1.7.3 Existing site, new theme

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.yaml or 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:

  1. In the R console, install the theme via blogdown::install_theme().

    blogdown::install_theme(theme = "lxndrblz/anatole")

  2. Manually move the configuration file (config.yaml or config.toml) from the themes/theme-name/exampleSite/ directory to the root directory of your website to match the newly installed theme.

  3. Carefully inspect the differences between your new theme’s exampleSite and the files inside your content/ folder. A theme’s exampleSite content 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.

1.7.4 Existing site, update theme

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.yaml or 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:

blogdown::install_theme(theme = "lxndrblz/anatole", force = TRUE)

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.

  1. Translated from her Chinese Weibo.↩︎

  2. For most themes, you can find this by navigating to the theme of your choice from http://themes.gohugo.io and then clicking on “Download.”↩︎