Book Structure

Overview

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. Book properties like the title, author and chapter structure are listed under book:

_quarto.yml

book:
  title: "mybook"
  author: "Jane Doe"
  date: "5/9/2021"
  chapters:
    - index.qmd
    - intro.qmd
    - summary.qmd
    - references.qmd

The index.qmd file is required (because Quarto books also produce a website in HTML format). This page should include the preface, acknowledgements, etc. The HTML version of the book will use the index.qmd as the home page and if provided, will place the cover-image on that page.
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):

_quarto.yml

bibliography: references.bib

Rendering options that should apply to all chapters for specific formats are listed under format:

_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:

intro.qmd

# Introduction

Note that the following is also still perfectly valid:

intro.qmd

---
title: "Introduction"
---

In the absence of a level-one header or a title set in the YAML front matter, the first header in the page will be used as the title.

Chapter Numbers

All chapters are numbered by default. If you want a chapter to be unnumbered simply add the .unnumbered class to its main header. For example, it is common to omit the chapter number for index.qmd:

index.qmd

# Preface {.unnumbered}

You can mix together numbered and unnumbered chapters. Note however that while you can link to unnumbered chapters, you can’t cross reference figures, tables, etc. within them. Unnumbered chapters are therefore mostly useful for prefatory content or references at the end of your book.

Section Numbers

You can set the numbering depth via the number-depth option. For example, to only number sections immediately below the chapter level, use this:

_quarto.yml

number-depth: 1

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:

_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:

references.qmd

# References {.unnumbered}

::: {#refs}
:::

Note that you can change the chapter title to whatever you like, remove .unnumbered to have it be numbered like other chapters, and add other content before or after the bibliography as necessary.

Creating an Index

For PDF output, you can create an index using the LaTeX makeidx package along with the \index command.

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:

_quarto.yml

format:
  html:
    theme: cosmo
  pdf:
    documentclass: scrreprt
    include-in-header: 
      text: |
        \usepackage{makeidx}
        \makeindex
    include-after-body: 
      text: |
        \printindex

Then, add \index{entry} commands wherever you want an index entry. For example:

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 package. This packages offers additional features for formatting the index. For example:

_quarto.yml

format:
  html:
    theme: cosmo
  pdf:
    documentclass: scrreprt
    include-in-header: 
      text: |
        \usepackage{imakeidx}
        \makeindex[intoc=true, columns=3, columnseprule=true, options=-s latex/indexstyles.ist]
    include-after-body: 
      text: |
        \printindex

In the above example, intoc=true will include an entry for the index into the table of contents, columns=3 will format the index into three columns, and columnseprule=true will display a line between index columns. Finally, options=-s latex/indexstyles.ist will use additional formatting options from an index-style file located at latex/indexstyles.ist. Many other features are available in the imakeidx package. Please refer to its documentation for further details.

Note that \index commands are automatically ignored for non-PDF output.

Parts & Appendices

Please Note

Note that EPUB and Word (Docx) formats do not currently support organizing books into parts. When rendering a book with parts to these formats, the parts will be ignored.

You can divide your book into parts using part within the book chapters. For example:

_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:

_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:

_quarto.yml

book:
  chapters:
    - index.qmd
    - intro.qmd
    - summary.qmd
    - references.qmd
  appendices:
    - tools.qmd
    - resources.qmd

Parts and appendices show up like this in HTML output:

A screenshot of the welcome page of a book rendered with Quarto. In the sidebar, content is separated by three different bold section titles. From top to bottom, these are: 'PROJECT 1: WEIGHTED DICE', 'PROJECT 2: PLAYING CARDS', and 'APPENDICES.'

In LaTeX output, the \part command is used for parts. In EPUB and MS Word output parts are ignored entirely.

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:

_quarto.yml

crossref:
  appendix-title: "App."
  appendix-delim: ":"

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.

Page Navigation

If you have a book 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:

_quarto.yml

book:
  page-navigation: true

When enabled, page navigation will be displayed at the bottom of the page whenever there is a next or previous page (including in the next or previous section). This option is enabled by default for books but not for websites.

You can also enable or disable page navigation at the page level by specifying page-navigation in the YAML header, e.g.:

basics.qmd

---
page-navigation: false
---

Or to control page navigation for all pages in a directory specify page-navigation in _metadata.yml:

_metadata.yml

page-navigation: false

Page Footer

Use the page-footer option to provide a common footer for all of the pages in a book. The simplest footer just provides text that will be centered and displayed in a lighter typeface:

_quarto.yml

book:
  page-footer: "Copyright 2021, Norah Jones"

You can alternatively target the left, right, and center regions of the footer individually:

_quarto.yml

book:
  page-footer: 
    left: "Copyright 2021, Norah Jones" 
    right: 
      - icon: github
        href: https://github.com/
      - icon: twitter 
        href: https://twitter.com/

Note for the right region of the footer we included navigational items for GitHub and Twitter rather than text. You can include navigational items in any region of the footer.

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:

_quarto.yml

book:
  page-footer:
    border: false

To use a light background (e.g. to match a navigation bar) you would do this:

_quarto.yml

book:
  page-footer:
    background: light

Unless specified, the color (foreground) used for elements that appear in the footer will be automatically determined by using a color that contrasts with the footer background.