github-starred/cs249r_book
2
0
Fork 0
mirror of https://github.com/harvard-edge/cs249r_book.git synced 2026-05-08 02:28:25 -05:00
Code Issues 85 Packages Projects Releases 24 Wiki Activity

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

New Issue
Closed
opened 2026-04-21 22:23:49 -05:00 by GiteaMirror · 0 comments
GiteaMirror commented 2026-04-21 22:23:49 -05:00
Owner
Copy Link

📋 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

  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:

  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-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-21 22:23:49 -05:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
area: book
area: collabs
area: kits
area: socratiq
area: tinytorch
area: tools
area: website
bug
dependencies
format: epub
format: pdf
link-health
link-rot
priority-high
pull-request
Mirrored from GitHub Pull Request
 staffml
type: bug
type: citation
type: code
type: errata
type: improvement
type: new
type: question
vault-sli
No Label pull-request
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
GiteaMirror ninjasurge
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: github-starred/cs249r_book#6530
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?