R Bookdown _bookdown.yml

Question

Bookdown has many configuration options and I am finding it hard to understand how to know whether an option exists, and the logic behind where these options are stated.

Answer 1

Here are some results of investigations into the codebase:

We can see that the 'config' variable in bookdown::render_book is populated from _bookdown.yml here, via a function called load_config which can be found in utils.R.

load_config seems to do two things - it stores the contents of config within a master options list called opts, of which config is just one element, and then returns that config element.

Note that opts is initially defined here. It is created from a knitr:::new_defaults which can be found here.

The config variable then appears in multiple parts of the codebase.

The following code is representative:

  if (is.na(new_session)) {
    new_session = FALSE
    if (is.logical(config[['new_session']])) new_session = config[['new_session']]
  }

So we can see that if new_session is passed directly to bookdown::render_book as a function argument, it is used. Otherwise an attempt is made to load it from the _bookdown.yml file.

The config is passed around a lot as an argument within bookdown::render_book. So for instance, we can see it being used in the source_files function in utils.R.

What do we conclude? _bookdown.yml allows you to populate a list of global options of the bookdown package. Whenever you see config (which is a list) being using the the codebase, you can set elements of this list by populating _bookdown.yml

I have not managed to find a comprehensive list of the options that can be specified in _bookdown.yml but one way of easily finding out what is possible is to search for examples on Github.