The .inv-table cells on slides/index.qmd hardcoded light-mode colors,
leaving the What's Included and Related Resources rows with text that
disappears on the dark background. Added dark-mode overrides for
column text, row hover, and last-column action links.
Extends PR #1633's instructors fix to the rest of the Quarto ecosystem.
Quarto renders floating sidebars with `<a class="sidebar-link">` and
`<a class="sidebar-item-toggle">` directly (not nested inside an
`.sidebar-item a` wrapper), so the legacy selector missed all real DOM
nodes.
Sites updated:
* slides, interviews, tinytorch/quarto, mlsysim/docs: full hardening
(toggle, leaf-link, active-state, search input, TOC rail).
* labs, kits, book/quarto: added missing search-input theming
(core sidebar and TOC fix already present from earlier work).
Each site's accent color is preserved: indigo for instructors and
interviews, pink for slides, amber for tinytorch, cyan for mlsysim,
teal for kits and labs, crimson for book.
Two issues caused the deployed slide PDFs to be unusable:
1. Every chapter .tex declared `\setsansfont{Helvetica Neue}` — proprietary
to Apple, not installed on the Ubuntu CI runner. xelatex bombed mid-frame,
the workflow's `|| true` swallowed the error, and the resulting PDF had
most text never typeset (blank pages with only logos/rules surviving).
Switch all 35 decks to TeX Gyre Heros (sans) and TeX Gyre Cursor (mono),
both bundled with texlive-fonts-extra — no external font downloads needed.
Drop the JetBrains Mono wget step and fonts-liberation from both slide
workflows accordingly.
2. Vol1 and Vol2 each ship `00_course_overview.pdf` and `01_introduction.pdf`.
The publish workflow uploaded them to a flat GitHub Release namespace, so
the second upload silently overwrote the first — clicking Vol I's Course
Overview actually downloaded Vol II's deck. Stage prefixed copies
(vol1_*.pdf, vol2_*.pdf) before upload, and update slides/vol{1,2}.qmd
plus the mlsysim cross-links to point at the new prefixed URLs.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Follow-up to #1424. The link-rot tracker reported 405 broken URLs on
the Slides site, dominated by `tinyMLx/courseware/raw/master/edX/...`
references. After de-duplicating, only 6 unique URLs were actually
broken — the other ~325 occurrences were references to those same
6 dead targets repeated across the deck inventory pages.
Cross-checking each broken path against the upstream repo's actual
contents (via the GitHub Contents API) revealed two categories:
CATEGORY A — file exists with extended title; URL needs encoding
- readings/5-11-1.pdf → readings/5-11-1%20Responsible%20AI%20Intro.pdf
- readings/5-11-3.pdf → readings/5-11-3%20Sustainable%20AI.pdf
Both upstream files contain the title in the filename
(e.g. "5-11-1 Responsible AI Intro.pdf"). The bare-number form in our
source matched the upstream README, which is itself broken; the
URL-encoded extended form returns 200.
CATEGORY B — file genuinely missing in upstream repo
- other/2-1-14.pdf ("Assignment Solution")
- readings/4-7-11.pdf ("Deploying a Multi-Tenant Application")
- slides/3-1-6.pdf ("What You'll Learn in This Course")
- slides/5-6-X.pdf ("Model Conversion") — `X` is a literal placeholder
in the upstream README too
No correct URL exists; the upstream README references these as
broken links. Replaced the entire `<a>` cell content with an em-dash
(—), preserving the table layout and the topic name in the adjacent
cell, but removing the broken link.
Files touched:
slides/tinyml-mlops.qmd (2 URL fixes + 1 em-dash)
slides/tinyml-applications.qmd (1 em-dash)
slides/tinyml-deploying.qmd (1 em-dash)
slides/tinyml-fundamentals.qmd (1 em-dash)
After this lands, the next nightly link-rot run should report Slides
site clean of `tinyMLx/courseware` failures.
Two surgical fixes for the nightly link-rot tracker (#1424):
1. **shared/config/.lycheeignore**: add two patterns that suppress
confirmed false positives reported in the tracker.
- JS template literals (`${m.github}`): when Lychee parses a .qmd
containing JavaScript with template literals like
`https://github.com/${m.github}`, the literal is URL-encoded in
the AST as `$%7B…%7D` and reported as broken. The literal is
substituted at runtime; it is never a real URL. Pattern matches
any `${ANY.ANY}` template-literal residue.
- GitHub avatar URLs (`github.com/<user>.png?size=N`): manually
verified that every avatar URL flagged by the tracker
(profvjreddi, Mjrovai, etc.) returns 200 in a browser. Lychee
unreliably HEADs them due to GitHub's avatar throttling.
Together these cover the 8 remaining "broken" links on the Unified
Site that are not real failures.
2. **slides/teaching.qmd**: replace a markdown link to
`.claude/rules/svg-style.md` with plain prose. The `.claude/`
directory is gitignored in this repo, so the URL
github.com/harvard-edge/cs249r_book/blob/main/.claude/rules/svg-style.md
404s. Mention the SVG style guide in prose without the broken link.
Out of scope for this patch: the 329 `tinyMLx/courseware/raw/master/...`
links in slides/, which point to PDFs that don't exist in the upstream
repo (the directory exists, but the specific file numbers don't). That
is a content/strategic question — needs a decision on whether to
upload missing PDFs, switch repos, or remove the links — and is left
for a separate workstream.
Iterates on the post-merge 404 redesign across all 8 sub-sites:
- SVG roofline-plot fonts bumped for readability without changing
layout: axis labels 9.5pt to 14pt, region labels 9.5pt to 14pt,
title and "your page (404)" annotation 11pt to 16pt.
- Random-joke font shrunk from 1.6rem to 1.3rem (1.1rem on mobile)
so the joke no longer dominates the SVG above it.
- Removed the static "Looks like this page slipped past our load
balancer" subline from 6 sub-sites — it read as a competing static
joke alongside the random rotation. Slides and instructors keep
their informational sublines.
- Joke pool tightened 97 to 79 via a strict ML-systems-centric test:
if you could swap "page" for any generic web/ops resource and the
joke still works, cut. Cuts removed the H&P canonical material
(Amdahl's Law, TLB miss, Dennard scaling, false sharing, fat-tree
topology) that is general computer architecture rather than ML
systems specifically. 19 borderline jokes were rewritten to anchor
punchlines in concepts only ML practitioners decode (KV cache,
gradient AllReduce, prefill, ZeRO, speculative-decode acceptance,
1F1B schedule, ridge point, BPE merges).
Replace the inline-game 404 across all 8 sub-sites with a unified
design: roofline-plot illustration, random pick from a 97-joke
editorial-curated pool, dual CTA (home + playground), and a
GitHub-issue-backed contribute link for community submissions.
The joke pool was curated through a multi-agent editorial process:
4 generators (each with a different ML systems lens) produced 240
candidates; 5 reviewer personas (architect, NLP researcher, production
engineer, undergrad, copy editor) scored each; the synthesizer kept 92
surviving jokes plus 5 new canonical-architecture additions (Amdahl,
TLB, Dennard, false sharing, fat-tree topology) the architect flagged
as missing from the H&P-tradition canon.
Self-contained CSS with prefers-color-scheme: dark adapts to host
themes without coupling to each sub-site's bespoke styling. SVG
follows the book's semantic palette (blue memory-bound slope, green
compute roof, MIT red error annotation). Per-site navigation
preserved across all sub-sites.
Adds .github/ISSUE_TEMPLATE/404_joke.yml so contributions arrive
structured (joke text, theme dropdown, license checkbox) and
auto-tagged (site, 404-joke, good-first-issue) for triage.
Align the MLSys·im code, docs, paper, website, workflows, and lab wheel for the 0.1.1 release. This also fixes runtime/API issues found during release review and prepares the paper PDF plus archive package.
Align public README and site messaging around the curriculum components, adoption paths, and current early-release status so newcomers can move from reading to building, deployment, practice, and teaching.
- Added font-family='Arial, Helvetica, sans-serif' to all SVG root tags to ensure clean, consistent textbook styling.
- Enforced strict high-contrast text colors, replacing pure black with a slightly softer dark gray (#333) for primary labels to adhere to the semantic style guide.
Audited all SVG figures in Volume 2 to align with textbook aesthetic guidelines.
- Replaced rounded corners (rx, ry) on <rect> elements with sharp corners.
- Converted assorted unapproved colors to the rigorous semantic palette
defined in the style guide (e.g. #cfe2f3 for compute, #d4edda for data,
#f9d6d5 for errors, plus standard grays).
- Automated a headless browser check (Puppeteer) to evaluate the rendered
layout, identifying and rectifying ~87 text element overlaps caused by
the font or box shifting. Adjusted coordinate spacing on problem files
such as the WSE and HBM architecture diagrams.
Every site's announcement bar now follows one template:
Line 1 — identity + primary CTA (what is THIS site)
Line 2 — the book (or, on book sites, the other volume)
Line 3 — "Alongside the book:" sibling row (3 most-relevant verbs)
Line 4 — newsletter
The book is the anchor of the curriculum; every other site is a verb
applied to it — TinyTorch (build), Hardware Kits (deploy), MLSys·im
(simulate), Labs (explore), Slides + Instructors (teach). Making that
shape visible in every bar turns nine independent sites into chapters
of one curriculum.
Removed stale copy: "Happy New Year!" on kits + labs, "coming in 2026"
on labs (we are in 2026; replaced with "Coming Summer 2026"), TinyTorch
v0.1.10 single-line release notice (belonged in a release changelog,
not the always-visible nav bar).
Normalized outbound links: /book -> /vol1/ and /vol2/, consistent
trailing-slash hygiene on every URL. Newsletter link points to
https://mlsysbook.ai/newsletter/ (the actual Quarto page) instead of
#subscribe (which only resolves on the landing page).
The landing site (mlsysbook.ai) uses a 5-line variant that covers all
four learner verbs + the teacher-tools row; every other site uses the
4-line form.
StaffML is a Next.js app, not a Quarto site, so its banner is out of
scope for this PR and will ship as a separate React component change.
Add `text` language tag to 25 unlabeled fenced code blocks across the
public-facing READMEs. Mostly directory-tree listings, all-contributors
bot instructions, and pseudo-output ASCII blocks — none were getting
syntax highlighting anyway, but the explicit tag silences markdownlint
MD040 and signals intent ("this is plain text, not a forgotten lang").
GitHub's github-markdown-css applies:
.markdown-body table { display: block; width: max-content; max-width: 100%; }
The HTML width="100%" attribute is a presentational hint with lower
specificity than the class selector, so tables with short cell content
were sizing to max-content and not stretching to fill the column.
Tables with long sentences per cell stretched fine, masking the bug.
Add inline style="width:100%" (specificity 1,0,0,0) which overrides
the class-selector rule. Keep width="100%" attribute as a fallback for
non-GitHub renderers (VSCode preview, GitLab, plain HTML viewers).
54 tables updated across 10 READMEs + the two contributor-sync scripts
that regenerate auto-managed tables.
The sub-project READMEs used an old-school nested-table card design
with hardcoded bgcolor="#ffffff", "#cfd6dd", "#eef2f7" plus deprecated
HTML4 attributes (cellpadding, cellspacing, border). It looked good in
light mode but produced harsh white islands in GitHub's dark theme,
which is what most readers see today.
Across 11 sub-READMEs:
- Strip the card wrapper so data tables are just clean
<table width="100%"> with semantic <thead>/<tbody>. Headers keep
their column widths; bgcolor/valign/zebra-stripe cruft is removed
(GitHub provides its own theme-aware striping).
- Convert the early-release callouts (and mlperf-edu's two-tier
status block + "source of truth" note + interviews' two info boxes)
to GitHub-native > [!NOTE] / > [!WARNING] / > [!TIP] callouts.
These are theme-aware, get proper icons, and render correctly in
light AND dark mode.
Net result: 528 lines of HTML cruft removed, 230 lines of clean
markdown added. Visual identity is preserved (callouts still stand
out, tables still stretch full-width) while becoming dark-mode safe
and consistent with the main README.
Add `width="100%"` to every HTML content and contributor table across all
project READMEs so they render full-width on GitHub instead of collapsing
to natural content width. Cell-level `width="X%"` percentages were already
in place but only take effect once the table itself has an explicit width.
Also update the contributor-sync scripts so the auto-generated tables stay
consistent on the next bot run:
- .github/workflows/contributors/generate_main_readme.py
- .github/workflows/contributors/generate_readme_tables.py
Scope: 27 files, 85 tables. Sub-project READMEs that already use the
"card" pattern (labs/, kits/ content sections with <table width="98%">
wrappers) are intentionally untouched.
- Add wrap_readme_data_tables.py to frame <table>+<thead>/<tbody> blocks in a
98% width panel (#cfd6dd border, #eef2f7 headers, zebra body rows where
applied manually in converted tables).
- Apply wraps to book, kits, labs, slides, tinytorch; tbody wraps for kits
docs/related and instructors overview.
- Convert remaining Markdown tables in mlsysim, mlperf-edu, and interviews to
the same HTML pattern; replace StaffML markdown callouts with HTML panels.
- Add thead rows to kits/instructors body-only tables for clearer hierarchy.
- mlperf-edu: stacked HTML panels (amber under construction + gray early-work
note) at top; replace workload-table markdown quote with HTML callout.
- slides, labs, mlsysim: rename DEV-BANNER comments to EARLY-RELEASE-CALLOUT
for consistency with other project READMEs.
Replace markdown blockquotes with a shared centered table pattern
(cellpadding, bgcolor panel, h3 + aligned paragraphs) so GitHub renders
consistent spacing. Align labs and mlsysim DEV-BANNER with the same layout
and 2026 messaging.
Use a short top-of-README callout for periodic-table, StaffML, TinyTorch,
slides, and instructors: live with the 2026 release, expect steady iteration,
link to GitHub issues. Slides banner replaces dev-only wording with the same
framing while keeping dev/live badges.
* feat(footer): build-time "last updated" stamp
Add a small build-time stamp to the page footer ("Last updated YYYY-MM-DD
· <site> · <commit>") so readers can see at a glance that the site is
fresh. Quarto's per-page `date-modified` already exists for chapter
pages, but it doesn't capture site-level rebuilds (theme tweaks,
navbar changes, deploy reruns).
Pieces:
- shared/scripts/inject-build-stamp.sh: wraps a token-replace over a
build directory. Search-and-replace on `<!-- MLSB_BUILD_STAMP -->`
means sites that haven't adopted the token are unaffected — opt-in
rollout per subsite.
- book/quarto/config/shared/html/footer-common.yml: token added next
to the existing copyright line in the shared book footer.
- shared/config/footer-site.yml: token added next to the copyright
in the unified-site footer.
- shared/config/site-head.html: minimal CSS for `.mlsb-build-stamp`
(small, neutral, dark-mode aware).
- .github/workflows/kits-publish-live.yml: representative wiring —
runs the stamp step after build and before deploy. Other publish-
live workflows can adopt the step the same way as they roll
through release-prep validation.
* feat(navbar): expose paper.pdf for TinyTorch / MLSys·im / StaffML
Each of these subsites already builds a companion paper.tex in CI and
ships the PDF alongside the HTML site. Surface those papers in the
navbar dropdowns where readers actually look for them:
Build menu:
- TinyTorch → site
- TinyTorch Paper (file-pdf icon, opens in new tab)
→ /tinytorch/assets/downloads/TinyTorch-Paper.pdf
- MLSys·im → site
- MLSys·im Paper (file-pdf icon, opens in new tab)
→ /mlsysim/mlsysim-paper.pdf
Prepare menu (after a separator):
- StaffML Paper (file-pdf icon, opens in new tab)
→ /staffml/downloads/StaffML-Paper.pdf
Paper URLs are intentionally kept in lockstep with the build steps in
tinytorch-publish-live (assets/downloads/), mlsysim-publish-live
(site root), and staffml-publish-live (out/downloads/). If a build
path moves, both the workflow and this navbar entry need to move
together — there is no single source.
* feat(404): per-site 404 pages for slides / instructors / unified site
The book, kits, labs, mlsysim, and tinytorch subsites already have
flavored 404.qmd pages that route lost readers to the right
neighborhood. Add the missing three so every subsite under
mlsysbook.ai has a coherent recovery experience instead of falling
back to GitHub Pages' default white-page 404.
- slides/404.qmd — slide-deck flavored copy, pointers back to
the deck index, the volumes, and the hub.
- instructors/404.qmd — instructor-flavored copy, pointers to the
course map, slides, and both volumes.
- site/404.qmd — landing-page flavored copy, the most
ecosystem-wide nav (links to every subsite)
because this is the most common 404 source
for inbound links from the legacy single-
volume mlsysbook.ai.
StaffML already has its own React not-found.tsx so no work needed.
TinyTorch's legacy Sphinx 404.md is preserved for now (still wired on
the Sphinx site that hasn't migrated yet).
* ci(precommit): block subsite-mirror drift on shared assets
Add a pre-commit hook that runs `shared/scripts/sync-mirrors.sh --check`
on every commit. The hook fails if any of the per-subsite real-file
mirrors (subscribe-modal.js, theme SCSS partials, logo) has drifted
from its canonical source in `shared/`.
Why a guard, not just a sync: Quarto's resource-copy step preserves
symlinks instead of dereferencing them, so we have to keep real
copies. Without the guard, "I'll edit the canonical and forget to
re-sync" silently re-introduces the duplicate-divergence bug we just
spent effort fixing. `always_run: true` because a mirror can drift via
deletion of the canonical, not just by editing the canonical itself.
To re-sync after a deliberate change:
bash shared/scripts/sync-mirrors.sh
* refactor(audit): duplicate-file finder + clean up obvious leftover
Add shared/scripts/find-duplicates.py as a periodic duplication
auditor. It SHA-1 hashes every source-y file across the ecosystem
roots, groups identical contents, subtracts the intentional groups
declared in shared/scripts/sync-mirrors.sh, and reports the rest as
unintended duplicates. JSON report written to .audit/duplicates.json
for CI ingest later; --strict makes it exit non-zero.
Defaults err on the side of being useful out of the box:
- Skips symlinks (those are deliberate aliases, not duplicates).
- Skips small files (<256B) — LICENSE stubs, .gitkeep, etc.
- Skips _site / _build / node_modules / .next / out / .git.
- Source-y suffix list (.js, .ts, .scss, .css, .html, .yml, .py, .sh).
Binary assets (images, PDFs) are NOT scanned because their dup
story is different (logos, icons are intentionally repeated).
Initial-cleanup pass:
- Delete tinytorch/scripts/cleanup_repo_history.sh — byte-identical
leftover; the canonical version lives at
tinytorch/tools/maintenance/cleanup_history.sh and is the one
referenced by tinytorch/tools/maintenance/README.md.
After this commit the only remaining unintended duplicate is
runHistoryProvider.ts in three vscode-ext packages (kits / labs /
tinytorch). Promoting that into a shared vscode-ext package is real
refactor work — out of scope for release-prep, captured for later.
Add .audit/ and _audit/ (the latter from the Playwright site-audit
script) to .gitignore.
* docs(release-prep): handoff notes covering all five PR groupings
Add a single document at the worktree root that walks through what
this branch contains, why each piece is there, the recommended PR
split (PR-1 safety-net, PR-2 visual polish, PR-3 scripts/audits/
cleanup, PR-4 TinyTorch prep, PR-5 cutover skeletons), what was
intentionally LEFT OUT (and why), and what verification was done
locally vs. what still needs the dev mirror to exercise.
Treat this as the cover memo for the staged-rollout foundation
work; once the five PRs are individually merged into dev, this file
will outlive the branch but the per-PR sections still document why
each piece exists for anyone debugging months from now.
Audit of the eight sub-project READMEs showed inconsistent surrounding
text around the auto-managed contributor table — some had a Legend line,
some didn't; instructors used a different heading style; interviews was
missing the thanks blurb and CTA; mlsysim was missing the END marker
and the recognition CTA.
Standardize all eight to the same template: heading + thanks blurb +
legend + ALL-CONTRIBUTORS markers + Recognize-a-contributor CTA.
Per-project quirks preserved: interviews keeps its closing author
sign-off paragraph; CTA wording stays project-specific (e.g. labs
suggests "code, tutorial, test, or doc" while kits suggests
"tool, test, video, or doc").
Per-project sections kept (not consolidated into root). Sub-READMEs
are landing pages, sub-projects could be extracted to standalone repos
later, and recognition is more meaningful where the work lives. The
root README continues to aggregate everything via the existing
sectioned tables.
Closes the gap where Slides and Instructor Site were first-class Quarto
sites but invisible to the contributor recognition pipeline, and fixes
two pre-existing holes for mlsysim/interviews.
Workflows
- all-contributors-add.yml: add `slides` and `instructors` to PROJECTS;
add `slide`/`instructor` aliases. Tighten the LLM prompt with explicit
multi-type and emoji/punctuation rules, and add a deterministic regex
fallback that scans the trigger comment for type keywords and unions
them with the LLM result so a flaky classification never drops a tag.
- update-contributors.yml: add `mlsysim`, `interviews`, `slides`,
`instructors` to the push trigger paths and to the file/commit lists,
so edits to those configs actually rebuild and push READMEs.
Generators
- generate_main_readme.py: refactor the per-section block to a single
PROJECT_SECTIONS table so adding a project is one line; add Slides
and Instructor Site sections.
- generate_readme_tables.py: register `slides` and `instructors`.
Configs / READMEs
- New `slides/.all-contributorsrc` and `instructors/.all-contributorsrc`
seeded with profvjreddi.
- Add ALL-CONTRIBUTORS-LIST markers + recognize-a-contributor blurb to
`slides/README.md` and `instructors/README.md`.
- Regenerate root, slides, instructors, and (sorted-badge drift) the
interviews README via the generators.
Docs
- Refresh `.github/workflows/contributors/README.md` to list all 8
projects and document the canonical-list-in-PROJECTS contract.
- Replace inline Google Fonts <link> tags in all 8 site configs with
a single `- file: shared/config/site-head.html` reference, so fonts
(Inter 400-800, JetBrains Mono) and Font Awesome are inherited from
one shared file instead of duplicated across every _quarto.yml
- Add missing Inter weight 800 (was only in site-head.html, not configs)
- Add carousel CSS + JS for MLSys·im landing page (arrows, dots, slides,
auto-rotation, keyboard nav) — fixes non-functional < > buttons
All 7 public-facing Quarto sites now have consistent announcement
bars with icon: megaphone, type: primary, position: below-navbar.
Previously only tinytorch, labs, kits, book, and mlsysim had them.
Establish a consistent convention across all subsite preview workflows:
- Every site uses SUBSITE_ROOT for source directory path
- Every site uses DEV_SUBSITE_PATH for deploy target path
- All output directories standardized to _build (slides was _build/html)
GitHub variables created/updated:
- INSTRUCTORS_ROOT=instructors (new)
- SLIDES_ROOT=slides (new)
- DEV_INSTRUCTORS_PATH=instructors (new)
- TINYTORCH_SITE=tinytorch/site-quarto (updated from tinytorch/site)
Updated workflows: instructors-preview-dev, slides-preview-dev,
slides-validate-dev, tinytorch-preview-dev. Also added announcement
modification step to instructors and tinytorch (matching kits pattern).
Add dark-mode.scss and enable dark theme in _quarto.yml so the slides
portal has the same dark mode toggle as all other Quarto sites.
Uses brightened Deep Rose (#F472B6) accent for dark backgrounds.
Replace duplicated navbar/mobile responsive rules in satellite sites
(instructors, kits, labs, mlsysim, slides) with a single import of
shared/styles/partials/_mobile.scss. Removes ~169 lines of copy-pasted
CSS that would drift out of sync when the shared partial is updated.
- instructors: remove rogue desktop padding, add _mobile import
- kits: remove ~50 lines of duplicated mobile rules, add _mobile import
- labs: remove ~55 lines of duplicated mobile rules, add _mobile import
- mlsysim: remove ~55 lines of duplicated mobile rules, add _mobile import
- slides: add _mobile import (had no mobile rules before)
Every subsite now sets $accent to its brand color and imports
shared/styles/partials/_navbar.scss instead of duplicating the
~40-line navbar block locally. Single source of truth for link
color, hover/active states, brand image height, icon-collapse
media query, and color-scheme toggle.
Drift fix: before this, instructors had font-size: 0.9rem +
weight 500 (making navbar look smaller than peer sites) and
slides had no navbar CSS at all (fell back to Bootstrap defaults).
Both now match the ecosystem.
Also renames $accent in labs/style.scss (previously hot pink
#e94560, used only by .coming-badge) to $coming-badge-pink to
free $accent for the ecosystem convention.
Net: -168 lines of duplicated SCSS across 6 files.
- interviews/staffml/LICENSE — MIT (app code, fork freely)
- interviews/LICENSE — All Rights Reserved (corpus, taxonomy, pipeline)
- book/LICENSE — CC BY-NC-ND 4.0 (educational content)
- kits/LICENSE — CC BY-NC-ND 4.0 (educational content)
- labs/LICENSE — CC BY-NC-ND 4.0 (educational content)
- slides/LICENSE — CC BY-NC-ND 4.0 (educational content)
- instructors/LICENSE — CC BY-NC-ND 4.0 (educational content)
The moat is the vault data, not the viewer. MIT for the app encourages
adoption and contributions. Proprietary for the corpus protects the IP.
Quarto strips <a> tags without href, so the data-tinyml JS approach
didn't work. Replaced with direct URLs on the badge elements:
topic name is plain text, SLIDES/READING/COLAB badges are <a> links
pointing to github.com/tinyMLx/courseware/raw/master/edX/...
- Removed JS script blocks from all TinyML pages
- 325 badge links now point directly to source PDFs
- Badge CSS updated for link styling with hover state
- Split single long tinyml.qmd into overview + 4 course detail pages
(fundamentals, applications, deploying, mlops)
- Each section now renders as its own module-card box
- Topic names with Slides/Reading/Colab badges instead of numbers
- Overview page shows 4 course cards with material counts
- Added Related Resources section linking syllabus, kits, textbook
- Moved shared styles (vol-grid, vol-card, section-header, inv-table)
from index.qmd inline to styles.css for reuse across pages
- Renamed navbar/sidebar to "TinyML Courseware"
Add TinyML (HarvardX edX Professional Certificate) as a peer of
Vol I and Vol II in the slides subsite. PDFs are served from the
tinyMLx/courseware repo via JS base URL pattern — zero binary
bloat in this repo.
- slides/tinyml.qmd: module-based catalog (5 chapters, 43 sections)
with human-readable titles and textbook cross-references
- slides/tinyml/README-edx-original.md: original edX curriculum map
- slides/styles.css: module-card, section-list, team-box components
- slides/index.qmd: TinyML card alongside Vol I/II
- slides/_quarto.yml: navbar dropdown + sidebar entry
- instructors/tinyml-syllabus.qmd: 10-12 week semester plan
- instructors/_quarto.yml: navbar + sidebar entry
- .github/workflows/slides-publish-live.yml: package TinyML ZIPs
from tinyMLx/courseware into the slides-latest release
Architecture:
- Merge landing, about, community, newsletter into one site/ project
- Move navbar-common.yml to shared/config/ (used by 12 configs)
- Create shared/config/footer-site.yml for centralized footer
- Create shared/scripts/subscribe-modal.js as canonical copy
- Single _quarto.yml replaces 4 independent configs
- One site_libs/ copy replaces four
Features gained:
- Google Analytics on ALL hub pages (was only on book volumes)
- Subscribe modal on landing page (was missing)
- Centralized footer with consistent links
Workflows updated:
- site-preview-dev.yml: matrix strategy → single build job
- site-publish-live.yml: loop over subsites → single build + deploy
- sync-newsletter.yml: builds from unified site project
- publish-all-live.yml: removed stale subsite input
- rewrite-dev-urls.sh: added --shallow flag for unified builds
All 12 navbar-common.yml references updated:
book vol1/vol2, site (unified), slides, instructors, interviews,
kits, labs, mlsysim
- Remove hero/splash layouts from slides, instructors, newsletter
- Switch all subsites to default Quarto layout (sidebar + TOC) matching kits pattern
- Add Google Fonts (Inter + JetBrains Mono) to slides portal
- Change instructors and interviews navbar from dark to light for consistency
- Replace indigo accent with crimson in instructors SCSS to match ecosystem
- Add slide preview carousel with 7 actual Beamer slide renders across Vol I and Vol II
Labs: moved the lab preview mockup before stats/CTAs so the experience
is the first thing visitors see after the title.
Slides: styled carousel arrows as dark circular buttons and added
pink dot indicators so users know they can browse slide previews.
Replace the generate-navbar.py script approach with direct metadata-files
references to navbar-common.yml. Quarto natively merges navbar arrays,
so site-local dropdowns defined inline in each _quarto.yml get appended
to the shared navbar automatically.
- Delete generate-navbar.py script (no longer needed)
- Delete all _navbar-generated.yml and _navbar-local.yml files
- Each subsite now references ../book/quarto/config/shared/html/navbar-common.yml
directly via metadata-files
- Sites with local dropdowns (slides, instructors, mlsysim) define them inline
in their _quarto.yml navbar.left — Quarto merges with the shared left items
- Zero tooling, zero generated files, zero maintenance scripts
Single source of truth for the navigation bar in navbar-common.yml.
New 5-dropdown structure: Read | Build | Teach | Community | About.
- Add generate-navbar.py script to merge shared + site-local dropdowns
- Add _navbar-local.yml for slides, instructors, mlsysim (site-specific menus)
- Generate _navbar-generated.yml for all 6 subsites (committed, no CI changes needed)
- Strip hardcoded navbars from all _quarto.yml configs (landing, vol1, vol2, slides,
instructors, mlsysim, kits, labs, newsletter)
- Add community/ and about/ paths to rewrite-dev-urls.sh for dev preview
To update navbar: edit navbar-common.yml, run generate-navbar.py --all, commit.
Add \mlsysbackup command to beamerthememlsys.sty that provides:
- Gray header bar (same size as crimson) with "Volume | Chapter | Backup"
- Gray section divider page matching the regular section page style
- Gray underline on frame titles instead of crimson
- Footer with "Backup" label appended
Update 01_introduction.tex to use the new command and drop redundant
"Backup:" prefix from frame titles.
- Wire up slides-preview-dev.yml to deploy via SSH (matching labs/kits pattern)
- Add slides/ URL rewrite in book-preview-dev.yml for landing page links
- Add pdf2pptx.py conversion script (pdftoppm + python-pptx, 300 DPI)
- Update Makefile with pptx targets (per-chapter, per-volume, all)
- Update slides-build-pdfs.yml and slides-publish-live.yml to build PPTX
and include PDF+PPTX ZIP archives in GitHub releases
- Fix all 44 overfull box warnings across 17 Vol1 Beamer decks
- Update slides portal pages with direct per-deck PDF/PPTX download links,
PPTX column in tables, and remove placeholder callouts
- Update teaching.qmd with PPTX build instructions
- Cross-link slides from instructors hub, getting-started, and both syllabi
Refresh top-level README with clearer volume naming, HTML branch
table, and consolidated support section. Replace ASCII art with
SVG diagrams in tinytorch milestones and labs. Streamline slides
and kits READMEs. Remove retired challenges/ directory.
~75 new slides across 35 decks based on systematic review of
slide content vs textbook chapters. All new slides have 5-component
speaker notes (LINK/NARRATE/ENGAGE/WARN/FLEX).
Quantitative exercises added (~20):
- Iron Law, roofline, memory budget, training cost calculations
- Chinchilla scaling, ZeRO memory, AllReduce crossover
- Tail latency SLO, DP noise calibration, Fermi estimates
War stories / case studies added (~8):
- Knight Capital $440M (deployment), COVID drift (data engineering)
- DistilBERT (compression), Tail at Scale (serving)
- OPT-175B failures (fault tolerance), Tesla IP theft (security)
Missing concept slides added (~25):
- Scaling law breakdowns, PFC deadlocks, checkpoint coordination
- Energy roofline, machine unlearning, robustness in GenAI
- Horowitz energy table, Pareto efficiency, diagnostic flowcharts
Generic backup slides replaced with chapter-specific content (all 35).
~15 new SVGs created for diagrams that needed visual support.
Section counters and pre-existing LaTeX bugs fixed across multiple decks.
Add "Why One Repository" section with authorial voice explaining the
integrated curriculum design. Replace flat component list with tiered
curriculum diagram (SVG) showing how textbook, labs, TinyTorch,
MLSys·im, hardware kits, and interview playbook connect. Split tables
into "For Students" and "For Educators" sections. Fix links so live
components point to mlsysbook.ai and in-development components point
to repo READMEs. Add dev banners to component READMEs (kits, mlsysim,
labs, interviews, slides). Update branch guide to clarify what is live
at mlsysbook.ai vs under development on dev.
Research-grounded speaker note upgrade across all 35 slide decks.
Every \note{} now follows the LINK/NARRATE/ENGAGE/WARN/FLEX structure
based on Shulman PCK, Chi ICAP, Rosenshine, Ambrose, Merrill, Bain,
Wiggins UbD, and Garner & Alley frameworks.
28 chapters upgraded in this commit (7 were upgraded in prior commit).
- NARRATE + FLEX on 100% of slides
- LINK, ENGAGE, WARN on key concept slides (~70%)
- ~70% CORE / ~30% OPTIONAL tags for pacing flexibility
- Every line unique to its specific slide — no generic filler
- No slide content changed — only speaker notes rewritten
