10.2 The directory structure

The default site generator in blogdown is Hugo (https://gohugo.io). A basic Hugo website usually contains the following files and directories:

  • config.toml
  • content/
  • static/
  • themes/
  • public/

The configuration file config.toml can be used to specify options for the Hugo website, e.g.,

baseURL = "/"
languageCode = "en-us"
title = "A Hugo website"
theme = "hugo-lithium-theme"

Some options are provided by Hugo itself, such as title and baseURL; you may refer to https://gohugo.io/getting-started/configuration/ for all built-in options. Some options are provided by the Hugo theme, and you need to read the documentation of the specific theme to know the additional options.

All source Markdown or R Markdown files should be placed under the content/ directory. The directory structure under content/ can be arbitrary.

The static/ directory contains static assets such as images and CSS files. Everything under static/ will be copied to the public/ directory when Hugo generates the website. For example, static/images/foo.png will be copied to public/images/foo.png, and if you want to include this image in your post, you may use ![title](/images/foo.png) in Markdown (the leading / typically indicates the root of public/).

You can download multiple themes to the themes directory. To activate a theme, specify its folder name in the theme option in config.toml. You can find a lot of Hugo themes from https://themes.gohugo.io. Remember, the best theme is always the next one, i.e., one that you have not used before. I recommend that you start with a simple theme (such as the default hugo-lithium theme in blogdown, hugo-xmin, or hugo-tanka), and write a substantial number of posts before seriously investing time in choosing or tweaking a theme.

After you serve a site using blogdown, your site will be continuously built to the public/ directory by default. You can upload this folder to any web server to deploy the website. However, if you know GIT, there is an even easier way to publish your website, to be introduced in the next section.

Hugo is very powerful and customizable. If you want to learn more technical details about it, you may read Chapter 2 of the blogdown book.