[PR #1410] [MERGED] fix(book): route per-volume builds to per-volume index pages #8177

New Issue

GiteaMirror · 2026-04-27T17:28:55-05:00

GiteaMirror commented

2026-04-27 17:28:55 -05:00

📋 Pull Request Information

Original PR: https://github.com/harvard-edge/cs249r_book/pull/1410
Author: @profvjreddi
Created: 4/19/2026
Status: ✅ Merged
Merged: 4/19/2026
Merged by: @profvjreddi

Base: dev ← Head: release-prep/vol-index-routing

📝 Commits (1)

edfe891 fix(book): route per-volume builds to per-volume index pages

📊 Changes

10 files changed (+279 additions, -8 deletions)

View changed files

📝 book/quarto/config/_quarto-epub-vol1.yml (+1 -1)
📝 book/quarto/config/_quarto-epub-vol2.yml (+1 -1)
📝 book/quarto/config/_quarto-html-vol1.yml (+1 -1)
📝 book/quarto/config/_quarto-html-vol2.yml (+1 -1)
📝 book/quarto/config/_quarto-pdf-vol1-copyedit.yml (+1 -1)
📝 book/quarto/config/_quarto-pdf-vol1.yml (+1 -1)
📝 book/quarto/config/_quarto-pdf-vol2-copyedit.yml (+1 -1)
📝 book/quarto/config/_quarto-pdf-vol2.yml (+1 -1)
➕ book/quarto/index-vol1.qmd (+135 -0)
➕ book/quarto/index-vol2.qmd (+136 -0)

📄 Description

Summary

Critical release-blocker: the deployed dev mirror's /book/vol1/ page renders vol2 content (h1 "Machine Learning Systems at Scale", vol2 cover image), and the cover image 404s on both volumes. Without this fix, the first vol1 publish to mlsysbook.ai would ship vol2's welcome page under the vol1 URL.

Root cause

Symlink misroutes vol1's index — book/quarto/index.qmd is a symlink to contents/vol2/index.qmd (commit 74cff1e833). Both _quarto-html-vol1.yml and _quarto-html-vol2.yml declare render: - index.qmd, so vol1 ends up rendering vol2's welcome content. The h1 we see on the live dev page proves this:
- https://harvard-edge.github.io/cs249r_book_dev/book/vol1/ → `
  Machine Learning Systems at Scale
  ` (that's vol2's title)
../../ cover/audio paths 404 — both contents/vol1/index.qmd and contents/vol2/index.qmd set the cover <img src> and podcast <source src> to ../../assets/.... Quarto leaves paths inside \``{=html}raw blocks verbatim, so on the deployed page at/book/volX/index.html, ../../assets/...resolves above the per-volume deploy root (where no asset exists) instead of the per-volumeassets/directory (where Quarto actually copies it viaresources:`).

Fix

Add real (non-symlink) book/quarto/index-vol1.qmd and book/quarto/index-vol2.qmd at the project root, copied from each volume's existing contents/volX/index.qmd with two corrections:
- Cover <img src> and podcast <source src> lose the ../../ prefix.
- output-file: index.html in the front matter so the rendered artifact lands as _build/html-volX/index.html directly (no redirect stub).
Point all 8 per-volume render blocks (html / pdf / pdf-copyedit / epub × vol1 / vol2) at index-volX.qmd instead of the shared index.qmd symlink.
Untouched on purpose: book/quarto/index.qmd (no longer rendered, kept for local dev tooling) and book/quarto/contents/volX/index.qmd (still the sidebar "Volume home" landing under each volume).

Verification (local)

```
cd book/quarto
quarto render index-vol1.qmd --to html
```

Produces a single _build/html-vol1/index.html (no redirect stub). Probed via python3 -m http.server:

URL	Before	After
`/` `<title>`	`Introduction to Machine Learning Systems`	same ✓
`/` `<h1 class="title">`	`Machine Learning Systems at Scale` (wrong, vol2)	`Introduction to Machine Learning Systems` ✓
`/assets/images/covers/cover-hardcover-book-vol1.png`	n/a (page used `../../`)	200 ✓
`/assets/media/notebooklm_podcast_mlsysbookai.mp3`	n/a (page used `../../`)	200 ✓

Test plan

book-validate-dev.yml builds vol1 and vol2 cleanly
After merge to dev, the dev-mirror smoke probe should show:
- /book/vol1/ → <h1 class="title">Introduction to Machine Learning Systems</h1>
- /book/vol1/assets/images/covers/cover-hardcover-book-vol1.png → 200
- /book/vol2/ → <h1 class="title">Machine Learning Systems at Scale</h1> (still correct)
- /book/vol2/assets/images/covers/cover-hardcover-book-vol2.png → 200
PDF/EPUB builds in CI complete without "missing input file" errors

Risk

Low. Diff is 8 single-line yml swaps + 2 new root files. Symlink and per-volume contents/ files are untouched. PDF/EPUB configs are updated symmetrically with HTML so no format will silently drift.

Discovered by

Live URL probing while preparing the staged release. The bug had been latent since the index symlink was repointed at vol2 during vol2 development; vol1 hadn't been re-published since.

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/harvard-edge/cs249r_book/pull/1410 **Author:** [@profvjreddi](https://github.com/profvjreddi) **Created:** 4/19/2026 **Status:** ✅ Merged **Merged:** 4/19/2026 **Merged by:** [@profvjreddi](https://github.com/profvjreddi) **Base:** `dev` ← **Head:** `release-prep/vol-index-routing` --- ### 📝 Commits (1) - [`edfe891`](https://github.com/harvard-edge/cs249r_book/commit/edfe8915afb03152f14c64e26a14f214634d34b0) fix(book): route per-volume builds to per-volume index pages ### 📊 Changes **10 files changed** (+279 additions, -8 deletions) <details> <summary>View changed files</summary> 📝 `book/quarto/config/_quarto-epub-vol1.yml` (+1 -1) 📝 `book/quarto/config/_quarto-epub-vol2.yml` (+1 -1) 📝 `book/quarto/config/_quarto-html-vol1.yml` (+1 -1) 📝 `book/quarto/config/_quarto-html-vol2.yml` (+1 -1) 📝 `book/quarto/config/_quarto-pdf-vol1-copyedit.yml` (+1 -1) 📝 `book/quarto/config/_quarto-pdf-vol1.yml` (+1 -1) 📝 `book/quarto/config/_quarto-pdf-vol2-copyedit.yml` (+1 -1) 📝 `book/quarto/config/_quarto-pdf-vol2.yml` (+1 -1) ➕ `book/quarto/index-vol1.qmd` (+135 -0) ➕ `book/quarto/index-vol2.qmd` (+136 -0) </details> ### 📄 Description ## Summary Critical release-blocker: the deployed dev mirror's `/book/vol1/` page renders **vol2 content** (h1 "Machine Learning Systems at Scale", vol2 cover image), and the cover image 404s on both volumes. Without this fix, the first vol1 publish to `mlsysbook.ai` would ship vol2's welcome page under the vol1 URL. ## Root cause 1. **Symlink misroutes vol1's index** — `book/quarto/index.qmd` is a symlink to `contents/vol2/index.qmd` (commit `74cff1e833`). Both `_quarto-html-vol1.yml` and `_quarto-html-vol2.yml` declare `render: - index.qmd`, so vol1 ends up rendering vol2's welcome content. The h1 we see on the live dev page proves this: - https://harvard-edge.github.io/cs249r_book_dev/book/vol1/ → \`<h1 class="title">Machine Learning Systems at Scale</h1>\` (that's vol2's title) 2. **`../../` cover/audio paths 404** — both `contents/vol1/index.qmd` and `contents/vol2/index.qmd` set the cover `<img src>` and podcast `<source src>` to `../../assets/...`. Quarto leaves paths inside `\`\`\`{=html}` raw blocks verbatim, so on the deployed page at `/book/volX/index.html`, `../../assets/...` resolves above the per-volume deploy root (where no asset exists) instead of the per-volume `assets/` directory (where Quarto actually copies it via `resources:`). ## Fix - Add real (non-symlink) `book/quarto/index-vol1.qmd` and `book/quarto/index-vol2.qmd` at the project root, copied from each volume's existing `contents/volX/index.qmd` with two corrections: - Cover `<img src>` and podcast `<source src>` lose the `../../` prefix. - `output-file: index.html` in the front matter so the rendered artifact lands as `_build/html-volX/index.html` directly (no redirect stub). - Point all 8 per-volume render blocks (html / pdf / pdf-copyedit / epub × vol1 / vol2) at `index-volX.qmd` instead of the shared `index.qmd` symlink. - **Untouched on purpose:** `book/quarto/index.qmd` (no longer rendered, kept for local dev tooling) and `book/quarto/contents/volX/index.qmd` (still the sidebar "Volume home" landing under each volume). ## Verification (local) \`\`\` cd book/quarto quarto render index-vol1.qmd --to html \`\`\` Produces a single `_build/html-vol1/index.html` (no redirect stub). Probed via `python3 -m http.server`: | URL | Before | After | |---|---|---| | `/` `<title>` | `Introduction to Machine Learning Systems` | same ✓ | | `/` `<h1 class="title">` | **`Machine Learning Systems at Scale`** (wrong, vol2) | `Introduction to Machine Learning Systems` ✓ | | `/assets/images/covers/cover-hardcover-book-vol1.png` | n/a (page used `../../`) | **200** ✓ | | `/assets/media/notebooklm_podcast_mlsysbookai.mp3` | n/a (page used `../../`) | **200** ✓ | ## Test plan - [ ] `book-validate-dev.yml` builds vol1 and vol2 cleanly - [ ] After merge to `dev`, the dev-mirror smoke probe should show: - `/book/vol1/` → `<h1 class="title">Introduction to Machine Learning Systems</h1>` - `/book/vol1/assets/images/covers/cover-hardcover-book-vol1.png` → 200 - `/book/vol2/` → `<h1 class="title">Machine Learning Systems at Scale</h1>` (still correct) - `/book/vol2/assets/images/covers/cover-hardcover-book-vol2.png` → 200 - [ ] PDF/EPUB builds in CI complete without "missing input file" errors ## Risk - **Low.** Diff is 8 single-line yml swaps + 2 new root files. Symlink and per-volume `contents/` files are untouched. PDF/EPUB configs are updated symmetrically with HTML so no format will silently drift. ## Discovered by Live URL probing while preparing the staged release. The bug had been latent since the index symlink was repointed at vol2 during vol2 development; vol1 hadn't been re-published since. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

GiteaMirror added the pull-request label 2026-04-27 17:28:55 -05:00

GiteaMirror closed this issue

2026-04-27 17:28:56 -05:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: github-starred/cs249r_book#8177