Merge pull request #1432 from quarto-dev/issue/5186

Clarify context of book options

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 `format`:
+
+``` {.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,38 +168,40 @@ 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"
-  date: "5/9/2021"
   chapters:
     - index.qmd
     - intro.qmd
@@ -193,12 +221,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 >}}

docs/websites/_footer.md

@@ -2,14 +2,14 @@
 
 Use the `page-footer` option to provide a common footer for all of the pages in a {{< meta project-type >}}. The simplest footer just provides text that will be centered and displayed in a lighter typeface:
 
-``` yaml
+```{.yaml filename="_quarto.yml"}
 {{< meta project-type >}}:
   page-footer: "Copyright 2021, Norah Jones" 
 ```
 
 You can alternatively target the `left`, `right`, and `center` regions of the footer individually:
 
-``` yaml
+```{.yaml filename="_quarto.yml"}
 {{< meta project-type >}}:
   page-footer: 
     left: "Copyright 2021, Norah Jones" 
@@ -24,15 +24,15 @@ Note for the `right` region of the footer we included navigational items for Git
 
 You can use the `background`, `foreground`, and `border` options to further control the appearance of the footer. By default, the footer has no background color and a top border. To eliminate the border you would do this:
 
-``` yaml
+```{.yaml filename="_quarto.yml"}
 {{< meta project-type >}}:
   page-footer:
     border: false
 ```
 
 To use a light background (e.g. to match a navigation bar) you would do this:
 
-``` yaml
+```{.yaml filename="_quarto.yml"}
 {{< meta project-type >}}:
   page-footer:
     background: light

docs/websites/_page-navigation.md

@@ -2,7 +2,7 @@
 
 If you have a {{< meta project-type >}} with several pages in a section or subsection, it is often convenient to offer the user the ability to navigate to the next page (or previous page) at the bottom of the page that they've just finished reading. You can enable this using:
 
-``` yaml
+```{.yaml filename="_quarto.yml"}
 {{< meta project-type >}}:
   page-navigation: true
 ```