Most efficient build for a book with online-only chapters and HTML/PDF output?

[friendly]

Description

I'm working on a large Quarto book (~15 chapters) that produces both HTML (via GitHub Pages) and PDF (CRC Press). I am using Quarto 1.9.36 on Windows 11, R 4.5.2, RStudio 2026.04.0+526

Some chapters are online-only (HTML appendices, absent from PDF), implemented using Quarto profiles (_quarto-online.yml, quarto-print.yml) as described in discussion #14365.

My current build script (constructed by Claude) is at: https://github.com/friendly/Vis-MLM-book/blob/master/build.sh.
Because I want an author index in the PDF, it does a neat computation on the @citation keys to see if anything has changed
before re-building that, and also offers a --dry-run option to see what would be done.

It takes ~30 min to render both versions. I'm wondering if Claude's analysis of what happens with a simple Build --> All formats is correct, and whether my build.sh script can be made more efficient.

How the script is organized

The script has three modes (--html, --pdf, --all) built around one constraint: the two formats must be rendered separately, because quarto render (all formats at once) fails on this book — during PDF cross-ref resolution it looks for .html files at the project root, but HTML output goes to docs/.

For HTML, a two-pass render seems to be needed:

quarto render --to html --profile online   # pass 1: builds the xref database
quarto render --to html --profile online   # pass 2: resolves forward xrefs in index.html

Pass 1 is necessary because index.qmd is rendered before later chapters exist in the xref database, so forward cross-references (e.g. @sec-pca-biplot) show section titles instead of numbers. Pass 2 picks up the completed database and fixes them.

For PDF, a single pass suffices, using the base config (no profile), which naturally excludes the online-only appendices:

quarto render --to pdf

A full --all build therefore runs three complete renders sequentially:

HTML pass 1  →  HTML pass 2  →  PDF

This takes ~25–30 minutes on my machine. The freeze cache speeds up partial
rebuilds (chapters whose source hasn't changed are skipped), but a full cold build
or one after editing a widely-used child doc still takes the full time.

Questions

1. Is the two-pass HTML render still necessary in current Quarto versions?
   Is there a flag or config option that forces index.qmd to wait for the full xref database before rendering, avoiding the second pass?

2. Is there a faster way to build both formats with profile-based chapter exclusion?
   For example, is there a way to run quarto render for all formats at once that avoids the root-vs-docs/ HTML path issue, perhaps via an output config option?

3. Any other known strategies for cutting build time on large Quarto books?
   (Beyond freeze cache, which we already use.)

[ImMike]

Both pain points are known and have cleaner workarounds than three sequential renders.

1. Is the two-pass HTML render still necessary?

Yes, when index.qmd references xrefs from later chapters that haven't yet entered the project xref database. There's no flag that forces index.qmd to wait, but you can sidestep the second pass by pre-populating the freeze cache:

# _quarto.yml
execute:
  freeze: auto

Commit _freeze/ once. After that, the first pass already sees a complete xref database, and the second pass becomes a no-op (~10 s instead of minutes). You can either drop pass 2 from build.sh entirely or keep it as a cheap idempotent safety net.

2. A faster way to build both formats together

The root cause of quarto render (all formats at once) failing is project.output-dir: docs — PDF cross-ref resolution expects intermediate .html artifacts next to the .qmd files, but they've been moved to docs/.

Option A - change the output dir (recommended)

project:
  type: book
  output-dir: _book        # not docs

format:
  html:
    output-file: index.html
  pdf: default

Then publish to GitHub Pages via an Actions step that copies _book/ to the gh-pages branch (or set Pages to serve from _book/ directly). With this single change:

• quarto render (no --to, no --profile) builds HTML + PDF in one pass
• Profile-based chapter exclusion still works via per-chapter profile: keys in the front-matter
• Total time drops to roughly one HTML + one PDF render — about 10–12 min in your range

Option B - keep output-dir: docs

Render in two steps but share the xref database:

quarto render --to html
quarto render --to pdf --use-freeze

--use-freeze forces PDF to re-use the HTML render's xref database instead of re-resolving from docs/, which avoids the root-vs-docs/ lookup that breaks the all-formats render.

---

Summary

Change	Time saved
Commit _freeze/, drop HTML pass 2	~5–8 min
Switch to output-dir: _book, single render	~10–15 min
Combined	~half of the current ~30 min build

[friendly]

Thanks so much for this great analysis!

One wrinkle is that, perhaps out of habit and that's what I'm comfortable with, I publish to https://friendly.github.io/Vis-MLM-book/ from docs/ on the master branch, rather than via gh-pages branch. I'll check out using a GitHub action.

Just to be clear, I presently have 3 _quarto*.yml files:

• _quarto.yml, containing: project:, book:, format: html, format:pdf, ... blocks

project:
  type: book
  output-dir: docs

book:
  title: "Visualizing Multivariate Data and Models in R"
  subtitle: "A Romance in Many Dimensions"
  output-file: "Vis-MLM"
  ...

• _quarto-print.yml, containing no project block, just the list of chapters for the print version, and PDF format block

# Print profile — PDF output, no online-only chapters
# Usage: quarto render --profile print

book:
  chapters:
    - index.qmd
    ...
format:
  pdf:
    documentclass: krantz
    classoption: [10pt, krantz2, titlepage, letterpaper]
    include-in-header: latex/preamble.tex
    include-before-body: latex/before-body.tex
    include-after-body: latex/after-body.tex
    output-file: Vis-MLM
    keep-tex: true
    latex-tinytex: true
   ...

• _quarto-online.yml, nothing except the additional Appendices

# Quarto "online" profile — extends _quarto.yml for the HTML build.
# Adds online-only appendices that are excluded from the PDF.
# Usage: quarto render --to html --profile online
#
# Quarto merges arrays (confirmed by cderv), so these entries APPEND to the
# base chapter list — they do not replace it. Do NOT duplicate chapters here.
# All format settings are already in _quarto.yml; no format overrides needed.

book:
  appendices:
    - 15-case-studies.qmd
    - Rcode.qmd
   

[mcanouil]

@ImMike using LLM to provide answers is allowed, but the information you provide must be fully verified.
Not verifying the information is a Code of Conduct violation.

• Setting output-dir to docs or whatever does not change anything in the process.
• "Profile-based chapter exclusion still works via per-chapter profile: keys in the front-matter" => this is totally wrong. There are no profile keys in front-matter.

There are possibly other wrong statements in the answer and I won't enumerate them all.

Important

As a member of the Quarto community, you are expected to follow our Code of Conduct, which outlines the standards of behavior and communication that we value. The Code of Conduct applies to all online interactions within the Quarto project, and it is enforced by the Quarto team. By participating in the Quarto community, you agree to abide by the Code of Conduct and respect the rights and dignity of others. You can find the Code of Conduct at https://github.com/quarto-dev/quarto-cli?tab=coc-ov-file#readme.

Thank you for your cooperation and contribution. 🙏

[mcanouil]

@friendly as you are using an LLM, you can use it to mostly address your optimisation questions.
It write your script in the first place.

Note also that Quarto CLI is indexed by deep wiki which could be used to get deeper knowledge of Quarto's internal.

---

1. Is the two-pass HTML render still necessary in current Quarto versions?
   Is there a flag or config option that forces index.qmd to wait for the full xref database before rendering, avoiding the second pass?

Answer: yes, that's how books work at least in Q1, but this is internal.
You shouldn't have to do this yourself.
No, there are no flags or options as the two pass is the implementation.

2. Is there a faster way to build both formats with profile-based chapter exclusion?
   For example, is there a way to run quarto render for all formats at once that avoids the root-vs-docs/ HTML path issue, perhaps via an output config option?

Answer: There is something wrong here as I don't understand why would the PDF reference HTML pages here.
I would need to dive into your repository to understand your Claude setup. You might want to ask Claude to simplify your setup and possibly go back to basics.
Note that your LLM script make things harder as it adds a lot of complexity for no obvious reasons.
Side note: debugging/optimising LLM outputs is not the goal of the discussion board.

3. Any other known strategies for cutting build time on large Quarto books?
   (Beyond freeze cache, which we already use.)

Freeze is for computation. If you don't have any, it does not matter.
So, currently that aren't any other native approaches.

---

What would help us and you, would be to create a very small project such as one created with quarto create project book, drop all the complexity from the script to focus on a sequential set of commands. (You can ask Claude to do small project using your profile setup)

[friendly]

Thanks for the mention of the Quarto Deep Wiki. I tried this, but it gives an error:

What is the best way to render a Quarto book in HTML and PDF when there are appendices meant to appear only in the online HTML version?
Fast
Error:An error occurred while running the query, please contact support

[mcanouil]

I did not say Deep Wiki was the answer, but that it could help. We are not maintaining Deep Wiki, so we can't do anything about their errors.

As your project is too complex to try to solve it, I reiterate:

What would help us and you, would be to create a very small project such as one created with quarto create project book, drop all the complexity from the script to focus on a sequential set of commands. (You can ask Claude to do small project using your profile setup)

It's easier to optimise/tweak a workflow on something small rather than spending several times 30 minutes on your project which is not required.