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.

Specifically I am finding it hard to describe what kind of options go in _bookdown.yml given that there are at least two other places for stating options:

• In _output.yml,
• Arguments to function calls such as bookdown::render_book.

It doesn't appear to me that there's any sort of 1 to 1 mapping between _bookdown.yml and arguments to functions like bookdown::render_book, so _bookdown.ymldoesn't seem to be just a different way of recording options to function calls.

We can see in the source code that `_bookdown.yml' is controlling some of the config options but not all of them.

So - to rephrase the question - why is _bookdown.yml a separate config file and where/what is the definition of what it should contain?

To take a representative example, there is a chapter_name option that can be used in _bookdown.yml. I have the following questions:

1. How are we supposed to know that this is an option, given that it is not referenced in the documentation here or even in the example here.
2. Once we know it exists, how do I found out what effect it has? Do all of these options get passed to other packages (e.g. pandoc, rmarkdown)? The only place I can find reference to chapter_name is in the CRAN source code for bookdown, and even there I can't really figure out how it's being used.

Note, the discussion of _bookdown.yml by the author is here, but I still don't fully understand.

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.