quarto-books

name

quarto-books

description

Create and edit multi-chapter Quarto book projects for HTML and/or PDF output. Use when the user asks to "create a Quarto book", "set up a book project", "add chapters", "organize a multi-chapter document", "create a textbook", "write technical documentation as a book", "configure book PDF output", "set up book navigation", or needs help with _quarto.yml book configuration, chapter organization, parts, appendices, cross-chapter references, or book deployment.

Quarto Book Projects

Create multi-chapter book projects that render to HTML (interactive website) and/or PDF. Books use a _quarto.yml configuration file and multiple .qmd chapter files.

Critical Rule: Relative Paths

All image paths, data file references, and resource links MUST be relative to each chapter file's location or the project root. Never use absolute paths.

# CORRECT — relative to this chapter file
![](images/figure.png)
![](../shared-images/diagram.png)

# WRONG
![](/absolute/path/to/book/images/figure.png)

Project Setup

Create a New Book

quarto create project book my-book
cd my-book
quarto preview

Minimal _quarto.yml

project:
  type: book
  output-dir: _book

book:
  title: "Book Title"
  author: "Author Name"
  date: today
  chapters:
    - index.qmd
    - intro.qmd
    - methods.qmd
    - results.qmd
    - references.qmd

format:
  html:
    theme: cosmo
  pdf:
    documentclass: scrreprt

Directory Structure

my-book/
├── _quarto.yml          # Book configuration
├── index.qmd            # Preface / homepage
├── intro.qmd            # Chapter 1
├── methods.qmd          # Chapter 2
├── results.qmd          # Chapter 3
├── references.qmd       # Bibliography
├── references.bib       # BibTeX file
├── images/              # Figures
├── data/                # Data files
├── _book/               # Output (gitignore this)
└── .gitignore

Chapter Organization

Parts and Chapters

book:
  chapters:
    - index.qmd
    - preface.qmd
    - part: "Part I: Foundations"
      chapters:
        - 01-introduction.qmd
        - 02-background.qmd
    - part: "Part II: Methods"
      chapters:
        - 03-approach.qmd
        - 04-implementation.qmd
    - part: "Part III: Results"
      chapters:
        - 05-findings.qmd
        - 06-discussion.qmd
    - conclusion.qmd
    - references.qmd

  appendices:
    - appendix-a.qmd
    - appendix-b.qmd

Chapter File Template

---
title: "Chapter Title"
---

# Main Heading {#sec-chapter-label}

Introduction paragraph.

## First Section {#sec-first}

Content with cross-references to @fig-example and @tbl-data.

## Summary

Chapter wrap-up.

Unnumbered Sections

# Preface {.unnumbered}

This section won't be numbered.

References Chapter

# References {.unnumbered}

::: {#refs}
:::

Cross-References Across Chapters

Enable chapter-based numbering:

crossref:
  chapters: true

Then reference elements in any chapter:

# In chapter 3:
As shown in @fig-results from @sec-methods...
See @tbl-data in the previous chapter.

Cross-reference prefixes: #fig-, #tbl-, #eq-, #sec-, #lst-, #thm-.

HTML Book Configuration

format:
  html:
    theme:
      light: cosmo
      dark: darkly
    toc: true
    toc-depth: 3
    number-sections: true
    code-fold: true
    code-tools: true

book:
  search: true
  page-navigation: true
  back-to-top-navigation: true
  reader-mode: true
  sidebar:
    style: docked
    collapse-level: 2
  repo-url: https://github.com/user/book
  repo-actions: [edit, source, issue]
  sharing: [twitter, linkedin]
  downloads: [pdf, epub]
  page-footer: "Copyright 2026 Author Name"

PDF Book Configuration

format:
  pdf:
    documentclass: scrreprt    # or scrbook, book, report
    classoption: [oneside, open=any]
    papersize: letter
    geometry:
      - top=30mm
      - left=30mm
      - right=30mm
      - bottom=30mm
    fontsize: 11pt
    mainfont: "TeX Gyre Termes"   # Requires xelatex/lualatex
    toc: true
    toc-depth: 3
    lof: true                     # List of figures
    lot: true                     # List of tables
    number-sections: true
    colorlinks: true
    keep-tex: false
    pdf-engine: lualatex
    include-in-header: preamble.tex

Custom LaTeX Preamble

Create preamble.tex for custom packages and commands:

\usepackage{tikz}
\newtheorem{theorem}{Theorem}[chapter]
\usepackage{fancyhdr}
\pagestyle{fancy}
\fancyhead[L]{\leftmark}
\fancyhead[R]{\thepage}

Bibliography

bibliography: references.bib
csl: chicago-author-date.csl

Use the same citation syntax as single documents (@key, [@key], etc.).

Computational Content

Freeze for Performance

execute:
  freeze: auto    # Only re-run when source changes
  cache: true

Per-Chapter Execution

In a chapter's YAML:

---
execute:
  echo: true
  warning: false
---

Deployment

GitHub Pages

quarto publish gh-pages

Quarto Pub

quarto publish quarto-pub

Netlify

quarto render
# Deploy _book/ directory to Netlify

GitHub Actions

Create .github/workflows/publish.yml:

name: Publish Book
on:
  push:
    branches: [main]
permissions:
  contents: read
  pages: write
  id-token: write
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: quarto-dev/quarto-actions/setup@v2
      - run: quarto render
      - uses: actions/upload-pages-artifact@v3
        with:
          path: ./_book
  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
    steps:
      - uses: actions/deploy-pages@v4

Best Practices

1. Naming: Use consistent chapter prefixes (01-intro.qmd, 02-methods.qmd) or descriptive names
2. Version control: Commit .qmd files and _quarto.yml; gitignore _book/
3. Images: Keep in a shared images/ directory at project root
4. Cross-references: Always use proper prefixes and unique labels
5. Bibliography: Keep references.bib at project root, share across chapters
6. Testing: Run quarto preview frequently during authoring

Resources

• references/book-yml-config.md — Complete _quarto.yml configuration reference for book projects
• references/pdf-book-setup.md — LaTeX document classes, typography, and advanced PDF customization
• references/deployment-guides.md — Platform-specific deployment instructions for GitHub Pages, Netlify, Quarto Pub, and more