6.1 Book Structure

book type projects are designed for authoring books. It combines multiple documents (chapters) into a single manuscript. It supports a variety of formats: PDF, HTML, EPUB, DOCX, etc.

Best to use book if you want both PDF and HTML outputs.

The _quarto.yml file contains the book project structure.

project:
  type: book
  output-dir: docs
  resources: 
    - "filters/emoji/*.png"

# only render changed files
execute:
  freeze: auto

book:
  title: "Title of the Book"
  site-url: "https://your-username.github.io/your-repo-name/"
  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
    - references.qmd
  appendices:
    - tools.qmd
    - resources.qmd

bibliography: references.bib

format:
  html:
    theme: cosmo
  pdf:
    documentclass: scrreprt
  epub:
    cover-image: cover.png

• The index.qmd file is required (because Quarto books also produce a website in HTML format). This page should include the preface, acknowledgements, etc.

• site-url: support RSS feeds, generates docs/sitemap.xml (for Google indexing).

• book specifies title, author, chatperters, and other book-level metadata.

  • chapters property includes one or more book chapters.

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

  • The references.qmd file will include the generated bibliography (see References below for details).

  Note that the markdown files dice.qmd and cards.qmd contain the part title (as a level one heading) as well as some introductory content for the part.

  If you just need a part title then you can alternatively use this syntax:

  book:
    chapters:
      - index.qmd
      - preface.qmd
      - part: "Dice"
        chapters: 
          - basics.qmd
          - packages.qmd

• format specifies output formats and their options.

  For example, you can specify themes for HTML and pdf macros.

If you would like to specify common metadata for documents inside a sub-directory our your project, you can do so by adding a file called _metadata.yml to the sub-directory. Read more in the Quarto Documentation at Directory Metadata.

• _metadata.yml will be merged to root _quarto.yml file, and will override any conflicting options in the root _quarto.yml file. → You can have distinct metadata for different sub-directories in your project.
• Another option is to use subfolder _quarto.yml. This will isolate your subfolder into a standalone project, and will not inherit any metadata from the root _quarto.yml file.

ref:

• Book Structure