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.4 Themes

A Hugo theme is a collection of template files and optional website assets such as CSS and JavaScript files. In a nutshell, a theme defines what your website looks like after your source content is rendered through the templates.

Hugo has provided a large number of user-contributed themes at https://themes.gohugo.io. Unless you are an experienced web designer, you’d better start from an existing theme here. The quality and complexity of these themes vary a lot, and you should choose one with caution. For example, you may take a look at the number of stars of a theme repository on GitHub, as well as whether the repository is still relatively active. Themes that have not been updated for a long time (e.g., a couple of years) may or may not still work with a later version of Hugo. You will have to test them carefully.

In this section, we will explain how the default theme in blogdown works, which may also give you some ideas about how to get started with other themes.

2.4.1 The default theme

The default theme in blogdown, hugo-lithium, is hosted on GitHub at https://github.com/yihui/hugo-lithium. It was originally written by Jonathan Rutheiser, and I have made several changes to it. This theme is suitable for those who prefer minimal styles, and want to build a website with a few pages and some blog posts.

Typically a theme repository on GitHub has a README file, which also serves as the documentation of the theme. After you read it, the next file to look for is config.toml under the exampleSite directory, which contains sample configurations for a website based on this theme. If a theme does not have a README file or exampleSite directory, you probably should not use it.

The config.toml of the theme hugo-lithium contains the following options:

baseurl = "/"
relativeurls = false
languageCode = "en-us"
title = "A Hugo website"
theme = "hugo-lithium"
ignoreFiles = ["\\.Rmd$", "\\.Rmarkdown", "_files$", "_cache$"]

[permalinks]
    post = "/:year/:month/:day/:slug/"

[[menu.main]]
    name = "About"
    url = "/about/"
[[menu.main]]
    name = "GitHub"
    url = "https://github.com/rstudio/blogdown"
[[menu.main]]
    name = "Twitter"
    url = "https://twitter.com/rstudio"

[params]
    description = "A website built through Hugo and blogdown."

    highlightjsVersion = "9.12.0"
    highlightjsCDN = "//cdnjs.cloudflare.com/ajax/libs"
    highlightjsLang = ["r", "yaml"]
    highlightjsTheme = "github"

    MathJaxCDN = "//cdnjs.cloudflare.com/ajax/libs"
    MathJaxVersion = "2.7.5"

[params.logo]
    url = "logo.png"
    width = 50
    height = 50
    alt = "Logo"

Some of these options may be obvious to understand, and some may need explanations:

  • baseurl: You can configure this option later, after you have a domain name for your website. Do not forget the trailing slash.

  • relativeurls: This is optional. You may want to set it to true only if you intend to view your website locally through your file viewer, e.g., double-click on an HTML file and view it in your browser. This option defaults to false in Hugo, and it means your website must be viewed through a web server, e.g., blogdown::serve_site() has provided a local web server, so you can preview your website locally when relativeurls = false.

  • title: The title of your website. Typically this is displayed in a web browser’s title bar or on a page tab.

  • theme: The directory name of the theme. You need to be very careful when changing themes, because one theme can be drastically different from another theme in terms of the configurations. It is quite possible that a different theme will not work with your current config.toml. Again, you have to read the documentation of a theme to know what options are supported or required.

  • ignoreFiles and permalinks: These options have been explained in Section 2.2.2.

  • menu: This list of options specifies the text and URL of menu items at the top. See Figure 1.5 for a sample page. You can change or add more menu items. If you want to order the items, you may assign a weight to each item, e.g.,

    [[menu.main]]
    name = "Home"
    url = "/"
    weight = 1
[[menu.main]]
    name = "About"
    url = "/about/"
    weight = 2
[[menu.main]]
    name = "GitHub"
    url = "https://github.com/rstudio/blogdown"
    weight = 3
[[menu.main]]
    name = "CV"
    url = "/vitae/"
    weight = 4
[[menu.main]]
    name = "Twitter"
    url = "https://twitter.com/rstudio"
    weight = 5

    In the above example, I added a menu item CV with the URL /vitae/, and there is supposed to be a corresponding source file vitae.md under the content/ directory to generate the page /vitae/index.html, so the link will actually function.

  • params: Miscellaneous parameters for the theme.

    • description: A brief description of your website. It is not visible on web pages (you can only see it from the HTML source), but should give search engines a hint about your website.

    • highlightjs*: These options are used to configure the JavaScript library highlight.js for syntax highlighting of code blocks on the web pages. You can change the version (e.g., 9.12.0), the CND host (e.g., using cdnjs: //cdnjs.cloudflare.com/ajax/libs), add more languages (e.g., ["r", "yaml", "tex"]), and change the theme (e.g., atom-one-light). See https://highlightjs.org/static/demo/ for all languages and themes that highlight.js supports.

    • MathJax*: The JavaScript library MathJax can render LaTeX math expressions on web pages. Similar to highlightjsCDN, you can specify the CDN host of MathJax, e.g., //cdnjs.cloudflare.com/ajax/libs, and you can also specify the version of MathJax.

    • logo: A list of options to define the logo of the website. By default, the image logo.png under the static/ directory is used.

If you want to be a theme developer and fully understand all the technical details about these options, you have to understand Hugo templates, which we will introduce in Section 2.5.