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. We do not recommend that you use a theme that has not been updated for more than a year.
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"
googleAnalytics = ""
disqusShortname = ""
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 totrueonly 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 tofalsein 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 whenrelativeurls = 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 currentconfig.toml. Again, you have to read the documentation of a theme to know what options are supported or required.googleAnalytics: The Google Analytics tracking ID (likeUA-000000-2). You can sign up at https://analytics.google.com to obtain a tracking ID.disqusShortname: The Disqus ID that you created during the account setup process at https://disqus.com. This is required to enable commenting on your site.26 Please note that you have to set up a functionalbaseurland publish your website before Disqus comments can work.ignoreFilesandpermalinks: 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.1 for a sample page. You can change or add more menu items. If you want to order the items, you may assign aweightto 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 = 5In the above example, I added a menu item
CVwith the URL/vitae/, and there is supposed to be a corresponding source filevitae.mdunder thecontent/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 tohighlightjsCDN, 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 imagelogo.pngunder thestatic/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.