R Bookdown _bookdown.yml
<p>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.</p>

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

<ul>
<li>In <code>_output.yml</code>, </li>
<li>Arguments to function calls such as <code>bookdown::render_book</code>.  </li>
</ul>

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

<p>We can see in the source code that `_bookdown.yml' is controlling some of the <a href="https://github.com/rstudio/bookdown/blob/7c09c9b22605686291e583ccad671ff7d84a1b35/R/html.R#L539" rel="noreferrer">config options</a> but not all of them.</p>

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

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

<ol>
<li>How are we supposed to know that this is an option, given that it is not referenced in the documentation <a href="https://cran.r-project.org/web/packages/bookdown/bookdown.pdf" rel="noreferrer">here</a> or even in the example <a href="https://bookdown.org/yihui/bookdown/configuration.html" rel="noreferrer">here</a>.</li>
<li>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 <code>chapter_name</code> is in the CRAN source code for <a href="https://github.com/rstudio/bookdown/blob/7c09c9b22605686291e583ccad671ff7d84a1b35/R/html.R#L539" rel="noreferrer">bookdown</a>, and even there I can't really figure out how it's being used.</li>
</ol>

<p>Note, the discussion of <code>_bookdown.yml</code> by the author is <a href="https://bookdown.org/yihui/bookdown/configuration.html" rel="noreferrer">here</a>, but I still don't fully understand.</p>