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
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.
config.toml of the theme
hugo-lithium contains the following options:
= "/" baseurl = false relativeurls = "en-us" languageCode = "A Hugo website" title = "hugo-lithium" theme = ["\\.Rmd$", "\\.Rmarkdown", "_files$", "_cache$"] ignoreFiles [permalinks]= "/:year/:month/:day/:slug/" post .main]] [[menu= "About" name = "/about/" url .main]] [[menu= "GitHub" name = "https://github.com/rstudio/blogdown" url .main]] [[menu= "Twitter" name = "https://twitter.com/rstudio" url [params]= "A website built through Hugo and blogdown." description = "9.12.0" highlightjsVersion = "//cdnjs.cloudflare.com/ajax/libs" highlightjsCDN = ["r", "yaml"] highlightjsLang = "github" highlightjsTheme = "//cdnjs.cloudflare.com/ajax/libs" MathJaxCDN = "2.7.5" MathJaxVersion .logo] [params= "logo.png" url = 50 width = 50 height = "Logo" alt
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
trueonly 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
falsein 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.
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
weightto each item, e.g.,
.main]] [[menu= "Home" name = "/" url = 1 weight .main]] [[menu= "About" name = "/about/" url = 2 weight .main]] [[menu= "GitHub" name = "https://github.com/rstudio/blogdown" url = 3 weight .main]] [[menu= "CV" name = "/vitae/" url = 4 weight .main]] [[menu= "Twitter" name = "https://twitter.com/rstudio" url = 5 weight
In the above example, I added a menu item
CVwith the URL
/vitae/, and there is supposed to be a corresponding source file
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.
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.
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
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.