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.5 Global options

The blogdown package uses global options, specified in a .Rprofile file, to help users customize how blogdown works. When you create a new site, blogdown adds a project-level .Rprofile file in the root directory of your website project.

Options should be set using the syntax options(name = value), and those included in a new blogdown site’s .Rprofile file are presented in Table 1.1.

TABLE 1.1: Global options for configured for new blogdown sites.
Option name Default Meaning
blogdown.hugo.version A valid Hugo version A Hugo version number
blogdown.knit.on_save TRUE Knit Rmd files automatically on save?
blogdown.method markdown The output format of .Rmd posts
blogdown.serve_site.startup FALSE Serve the site on RStudio startup?

Three of these options are worth further explanations:

  • blogdown.hugo.version: You can find available Hugo versions at https://github.com/gohugoio/hugo/releases/, and find all locally installed Hugo versions via blogdown::find_hugo('all'). A common mistake when specifying this option is to omit the version number 0 at the end. For example, only Hugo v0.55.0 exists, but not v0.55, so options(blogdown.hugo.version = '0.55') will not work, and you must set it to 0.55.0 precisely.

  • blogdown.knit.on_save: By default, the Rmd file is automatically knitted when it is saved. If you prefer clicking the Knit button in RStudio to manually knit the file, you may set this option to FALSE. If this option is unset, blogdown will set it to TRUE for the current R session (with a reminder message) when you click the Knit button.

  • blogdown.method: By default, an Rmd post is compiled to .md (Markdown) via rmarkdown, which will be rendered to HTML by Hugo’s Markdown renderer (e.g., Goldmark). You may set this option to "html" to pre-render .md to .html and bypass Hugo’s Markdown renderer. Basically, this option decides whether you want to use Pandoc or Hugo’s Markdown renderer to render Markdown to HTML. See Section @ref{blogdown-method} for more information.

We recommend that you set these options in your R startup profile file. If you have never used a startup profile file before, you can check out the help page ?Rprofile. Here, we provide a brief but incomplete introduction to orient you quickly.

A startup profile file is basically an R script that is executed when your R session is started. This is a perfect place to set global options, so you do not need to type these options again every time you start a new R session.

There are a few things you need to know about R’s startup profile file before using:

  1. You can use a global profile file ~/.Rprofile,10 or a per-project file .Rprofile under the root directory of your RStudio project. The former will be applied to all R sessions that you start, unless you have provided the latter to override it.

  2. The name “startup profile file” means that R only executes this file when you first start your R session. This means that when you modify and save your .Rprofile, you must restart R for the changes to take effect.

  3. R will silently ignore the last line of your .Rprofile if it does not have a trailing newline, so please make sure you add at least one newline to the end of your .Rprofile.

If you want to add a profile file to an existing blogdown project, or you created a new website without using blogdown::new_site(), you can create a boilerplate version with this command in your R console:

blogdown::config_Rprofile()

This is the easiest way to create or modify a per-project profile file. At the top of the file in a new blogdown website project, you will see this:

# REMEMBER to restart R after you modify and save this file!

# First, execute the global .Rprofile if it exists. You may
# configure blogdown options there, too, so they apply to any
# blogdown projects. Feel free to ignore this part if it sounds
# too complicated to you.
if (file.exists("~/.Rprofile")) {
  base::sys.source("~/.Rprofile", envir = environment())
}

First, note the top message! The next section of code is necessary to execute both your project profile as well as the global profile if one exists. R only reads one startup profile file. For example, if you have a .Rprofile under the current directory and a global ~/.Rprofile, only the former one will be executed when R starts up from the current directory. This code is provided for you so you may execute both a global and per-project profile file. Note that this code should only live in the project profile, and you must not add it to your global ~/.Rprofile, otherwise it will trigger an infinite recursion.

Below that, you will set your options. These can be stacked on separate lines, or you may use commas to list multiple options together:

# stacked options
options(blogdown.serve_site.startup = FALSE)
options(blogdown.knit.on_save = TRUE)

# comma-separated options
options(blogdown.serve_site.startup = FALSE,
        blogdown.knit.on_save = TRUE)

It is up to you how to format your profile file—either way works. The blogdown options provided in the boilerplate profile file are just a subset of the options available. Depending on your personal preferences and the theme you choose, you may wish to set more global options as you work on your website. For example:

TABLE 1.2: Additional global options that affect the behavior of blogdown.
Option name Default Meaning
blogdown.author The default author of new posts
blogdown.ext .md Default extension of new posts: .md / .Rmd / .Rmarkdown
blogdown.subdir post Default subdirectory under content/ for new posts
blogdown.yaml.empty TRUE Preserve empty fields in YAML?

Suppose you always prefer writing .Rmd posts (instead of the default .md), and want the author of new posts to be “John Doe” by default. You can set these options in the profile file:

options(blogdown.ext = ".Rmd", blogdown.author = "John Doe",
  blogdown.subdir = "blog")

A nice consequence of setting these options is that when you use the RStudio addin “New Post,” the fields “Author,” “Subdirectory,” and “Format” will be automatically populated, so you do not need to manipulate them every time, unless you want to change the defaults.

One inconvenience when using startup profile files is the case of the team-authored blog, where multiple authors collaborate on the same website project. You cannot set author-specific options using the blogdown.author option in a single .Rprofile, because this option should be different for different authors. One workaround is to set common website options in your project .Rprofile, then allow each individual author to set their own author-specific options in the global ~/.Rprofile on each author’s computer. If you use the boilerplate blogdown::config_Rprofile(), the first chunk of code at the top will ensure that the global ~/.Rprofile is also executed if it exists.


  1. The tilde ~ denotes your home directory in your system.↩︎