Clarify context of options

(cherry picked from commit ee5ca05)

Author: cwickham

docs/books/book-structure.qmd

@@ -8,9 +8,10 @@ project-type: book
 
 The structure of a Quarto book can be as simple as a list of chapters, or can alternatively incorporate multiple parts and/or appendices. Quarto book chapters and sections are automatically numbered (for cross-referencing), however you can also specify that some parts of the book should remain unnumbered.
 
-The simple book configuration generated by `quarto create project book` illustrates the basics:
+The simple book configuration generated by `quarto create project book` illustrates the basics. 
+Book properties like the title, author and chapter structure are listed under `book`:
 
-``` yaml
+``` {.yaml filename="_quarto.yml"}
 book:
   title: "mybook"
   author: "Jane Doe"
@@ -26,17 +27,33 @@ book:
 -   The remainder of `chapters` includes one or more book chapters.
 -   The `references.qmd` file will include the generated bibliography (see [References] below for details).
 
+Rendering options that should apply to all chapters and all formats are listed at the top-level of `_quarto.yml`(i.e. not nested under `book`):
+
+``` {.yaml filename="_quarto.yml"}
+bibliography: references.bib
+```
+
+Rendering options that should apply to all chapters for specific formats are listed under `formats`:
+
+``` {.yaml filename="_quarto.yml"}
+format:
+  html:
+    theme: cosmo
+  pdf:
+    documentclass: scrreprt
+```
+
 ## Titles
 
 Since rendering options are provided in `_quarto.yml`, you'll typically see a simple level-one header at the top of chapters. For example:
 
-``` markdown
+``` {.markdown filename="intro.qmd"}
 # Introduction
 ```
 
 Note that the following is also still perfectly valid:
 
-``` yaml
+```{.yaml filename="intro.qmd"}
 ---
 title: "Introduction"
 ---
@@ -58,17 +75,26 @@ You can mix together numbered and unnumbered chapters. Note however that while y
 
 You can set the numbering depth via the `number-depth` option. For example, to only number sections immediately below the chapter level, use this:
 
-``` yaml
+```{.yaml filename="_quarto.yml"}
 number-depth: 1
 ```
 
-Note that `toc-depth` is independent of `number-depth` (i.e. you can have unnumbered entries in the TOC if they are masked out from numbering by `number-depth`).
+Note that `number-depth` is a format option, not a `book` option so it is placed at the top-level of `_quarto.yml`, not nested under `book`. 
+If you want `number-depth` to only apply to a certain format, nest it under `format`:
+
+```{.yaml filename="_quarto.yml"}
+format:
+  pdf:
+    number-depth: 1
+```
+
+The `toc-depth` option is independent of `number-depth` (i.e. you can have unnumbered entries in the TOC if they are masked out from numbering by `number-depth`).
 
 ## References
 
 You should include a `div` with the id `#refs` at the location in your book where you'd like the bibliography to be generated. For example the `references.qmd` file generated by `quarto create project book` includes this:
 
-``` markdown
+```{.markdown filename="references.qmd"}
 # References {.unnumbered}
 
 ::: {#refs}
@@ -83,7 +109,7 @@ For PDF output, you can create an index using the LaTeX [makeidx](https://ctan.o
 
 To add an index to the PDF output for a book, add these `include-in-header` and `include-after-body` entries to your `pdf` format configuration in `_quarto.yml`:
 
-``` yaml
+```{.yaml filename="_quarto.yml"}
 format:
   html:
     theme: cosmo
@@ -100,15 +126,15 @@ format:
 
 Then, add `\index{entry}` commands wherever you want an index entry. For example:
 
-``` latex
+```{.latex filename="chapter.qmd"}
 Markdown\index{Markdown} allows you to write using
 an easy-to-read, easy-to-write plain text format.
 ```
 
 Alternatively, you can also use the [imakeidx](https://ctan.org/pkg/imakeidx) package.
 This packages offers additional features for formatting the index. For example:
 
-``` yaml
+```{.yaml filename="_quarto.yml"}
 format:
   html:
     theme: cosmo
@@ -142,34 +168,39 @@ Note that EPUB and Word (Docx) formats do not currently support organizing books
 
 You can divide your book into parts using `part` within the book `chapters`. For example:
 
-``` yaml
-chapters:
-  - index.qmd
-  - preface.qmd
-  - part: dice.qmd
-    chapters: 
-      - basics.qmd
-      - packages.qmd
-  - part: cards.qmd
-    chapters:
-      - objects.qmd
-      - notation.qmd
-      - modifying.qmd
-      - environments.qmd
+```{.yaml filename="_quarto.yml"}
+book:
+  chapters:
+    - index.qmd
+    - preface.qmd
+    - part: dice.qmd
+      chapters: 
+        - basics.qmd
+        - packages.qmd
+    - part: cards.qmd
+      chapters:
+        - objects.qmd
+        - notation.qmd
+        - modifying.qmd
+        - environments.qmd
 ```
 
 Note that the markdown files `dice.qmd` and `cards.qmd` contain the part title (as a level one header) as well as some introductory content for the part. If you just need a part title then you can alternatively use this syntax:
 
-``` yaml
-- part: "Dice"
-  chapters: 
-    - basics.qmd
-    - packages.qmd
+```{.yaml filename="_quarto.yml"}
+book:
+  chapters:
+    - index.qmd
+    - preface.qmd
+    - part: "Dice"
+      chapters: 
+        - basics.qmd
+        - packages.qmd
 ```
 
 You can include appendices by adding an `appendices` key to your `book` config. For example:
 
-``` yaml
+```{.yaml filename="_quarto.yml"}
 book:
   title: "mybook"
   author: "Jane Doe"
@@ -193,12 +224,15 @@ In LaTeX output, the `\part` command is used for parts. In EPUB and MS Word outp
 
 Appendices are numbered using uppercase alpha, and have a prefix inserted into their title to indicate they are an appendix (e.g. "Appendix A --- Additional Resources"). You can customize the prefix and delimiter using the following options:
 
-``` yaml
+```{.yaml filename="_quarto.yml"}
 crossref:
   appendix-title: "App."
   appendix-delim: ":"
 ```
 
-Which would result in the above example being output as: "App. A: Additional Resources".
+Which would result in the above example being output as: "App. A: Additional Resources". 
+Note that `crossref` is a format option and is not nested under `book`.
+
+{{< include ../websites/_page-navigation.md >}} 
 
-{{< include ../websites/_page-navigation.md >}} {{< include ../websites/_footer.md >}}
+{{< include ../websites/_footer.md >}}