Add What You Need to Start, For Instructors, and Make It Better sections; broaden The Bigger Picture with the build-deploy-test arc and the breadboard/FPGA/TinyOS tradition; route resource links through mlsysbook.ai and the repo via mlsysbook.ai/git; drop em-dashes and contractions for house style.
The subtitle script injected the 'Machine Learning Systems' link as a
sibling of the logo <img>, which sits inside Quarto's
<a class="sidebar-logo-link"> wrapper. That nested our anchor inside the
logo anchor (invalid HTML), so clicking it fired the outer logo link
(./index.html) instead of navigating to the book. Insert the subtitle
after the logo anchor as a child of .sidebar-header so the link works.
The version chip keys off subtitle.parentNode and is fixed by the same move.
Every subsite's announcement bar Line 1 carried a 'Start reading →' / 'Start building →' / 'Get started →' link that pointed at the very subsite the reader was already on. Clicking it was a no-op self-navigation.
Strip the CTA from Line 1 across all 8 sites that have the regression:
- announcement-vol1.yml drop 'Start reading →'
- announcement-vol2.yml drop 'Start reading →'
- tinytorch drop 'Start building →'
- mlsysim drop 'Get started →'
- kits drop 'Get started →'
- labs drop 'Preview →'
- slides drop 'Browse decks →'
- instructors drop 'Start here →'
Line 1 keeps the bold identity statement, which is what readers came for. The other lines (Vol I / II links, sibling row, newsletter CTA) keep their navigations since they DO lead somewhere new.
announcement-book.yml is unchanged — its Line 1 already points at the ecosystem root (https://mlsysbook.ai/), not at /book/ where the reader is.
Two related fixes to the chip JS in sidebar-subtitle.html:
1. Bump the chip's literal from v0.1.10 to v0.1.11 to match the actual current release. The v0.1.11 publish-live (commit 3449ee7050) bumped settings.ini and the README badge but did not propagate to the chip, so the live site shows the announcement bar saying 'v0.1.11 released' next to a chip still saying v0.1.10. The companion ci(tinytorch-publish-live) commit on this branch adds the missing UPDATE_VERSION sed step so this never drifts again.
2. Remove the version reference from the doc comment ('The chip's v0.1.10 ...' → 'The chip's version literal ...') so the comment no longer needs to be bumped alongside the literal. The // TINYTORCH_VERSION_CHIP sed marker is still anchored on the literal line and is the single source the workflow targets.
For the public launch, every site's "Alongside the book" (or "Build
with your students") row now lists StaffML alongside TinyTorch, Hardware
Kits, MLSys·im, and Labs. Two coupled changes:
• StaffML appended with verb "practice" — pairs cleanly with the
existing verbs (build / deploy / model / explore / practice).
• MLSys·im verb changed from "simulate" to "model" to match the
project's own self-description ("first-principles analytical
modeling for ML training and inference; model the physics before
you build"). MLSys·im is analytical, not Monte-Carlo simulation;
the new verb is more honest and the audience reads it cleanly.
Also restores tinytorch/quarto/config/announcement.yml to the canonical
4-line ecosystem template. That file had been silently rewritten to a
release-only banner ("🎉 v0.1.11 released — ...") by the
tinytorch-publish-live workflow, dropping the ecosystem cross-links
entirely. Restoration here; workflow fix is a separate commit.
Per-site row state after this commit (each site omits itself):
site, vol1, vol2: TinyTorch · Kits · MLSys·im · Labs · StaffML
instructors: TinyTorch · Kits · Slides · StaffML
kits: TinyTorch · MLSys·im · Labs · StaffML
labs: TinyTorch · Kits · MLSys·im · StaffML
mlsysim: TinyTorch · Kits · Labs · StaffML
tinytorch: Kits · MLSys·im · Labs · StaffML
slides: (teacher-focused row, unchanged)
The staffml site itself has its own Next.js ecosystem navbar
(EcosystemBar.tsx) which is out of scope for this Quarto-only sweep
and audited separately.
* Document GELU activation function in 02_activations.qmd
Added GELU activation function explanation and implementation.
* docs(tinytorch): add GELU implementation
This commit adds the GELU activation function implementation to the 2nd module in the docs.
* Update GELU code to reflect src code change
Refactor GELU activation to use a simplified sigmoid approximation.
* docs(tinytorch): polish GELU activation section
---------
Co-authored-by: Vijay Janapa Reddi <vj@eecs.harvard.edu>
The original hardening got the structural selectors right, but the
labs/kits/book sidebar still had two divergences from the instructors
reference: (a) section headers and leaf links rendered with the same
muted color (no hierarchy) because the section-header rule only matched
the chevron `<a class="sidebar-item-toggle">` and missed the section
text `<a class="sidebar-link text-start">`, and (b) the active-state
rule colored the text in the accent color rather than white on a subtle
accent tint, so active links read as loud accent fills instead of the
clean instructors look.
Changes per file:
* labs/, kits/: extend section-header selector list to include
`a.sidebar-link.text-start`; drop `font-weight: 400 !important` from
the leaf rule so the section-header weight (600) wins on elements
matching both; move active-state color/background/weight into the
high-specificity `#quarto-sidebar` guard block to beat Bootstrap's
default `.sidebar-link.active { color: var(--bs-primary) }`.
* book/quarto/: same treatment, plus include `.part-divider` in the
section-header selector list to keep the part-divider hierarchy.
* tinytorch/quarto/: same active-state hardening, plus rename
`$accent` → `$accent-dark` throughout (the theme partial
shared/styles/themes/_theme-tinytorch.scss declares both variables;
since Quarto auto-`!default`s every scss:defaults declaration, the
reassignment of `$accent` here was silently ignored and rgba calls
resolved with the light #D4740C value). Drop the unused
`$link-color-dark` definition that referenced `$accent-dark` from
scss:defaults — Quarto hoists user defaults above shared partial
defaults, so `$accent-dark` isn't yet defined when that line runs.
Rules in scss:rules resolve `$accent-dark` correctly because rules
are processed after all defaults are merged.
Verified with Playwright probes on /vol1.html (slides), /index.html
(labs, kits), /big-picture.html (tinytorch), /api-stability.html
(mlsysim), /foundations-syllabus.html (instructors): all six now show
white active text on rgba(accent, 0.15) tint, weight 500, with bright
section headers (#e6e6e6) at weight 600 and muted leaf links (#888888
or #cbd5e1).
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.
The h3 and pre code rules set near-white colors unconditionally, which
made these elements unreadable in light mode. Gate them on
[data-bs-theme="dark"] so light mode falls back to its own contrast.
Adopt the shared release-versioning pattern. Pure additions: no
existing build steps, configs, or sources are touched. The 6-place
manual version sprawl in the publish workflow stays as-is —
pyproject.toml remains the canonical source the manifest READS from.
quarto/_quarto.yml:
- <meta name="release-manifest" content="/tinytorch/release-manifest.json">
added to include-in-header so the pill's runtime fetch resolves
correctly under /tinytorch/.
- shared/release/release-pill.html added to include-after-body so
every rendered page carries the pill in the DOM.
.github/workflows/tinytorch-publish-live.yml:
- New "📦 Emit release manifest" step inserted between the slide-deck
download and the gh-pages deploy. Runs scripts/version/release.py
compute-hash over modules/, quarto/ (excluding _build), pyproject.toml,
MANIFEST.in. Writes release-manifest.json into the site build dir
so it deploys at /tinytorch/release-manifest.json.
The pill is best-effort chrome — silent if the manifest is missing,
which keeps preview-dev and local renders from breaking. Production
publishes always emit it before deploy, so the live site shows
"TinyTorch v0.1.10 · Apr 28, 2026" in the footer once this lands.
Three small but layered fixes that together make every page under the
tito CLI module fully readable in light mode, dark mode, and the hybrid
state where data-bs-theme="dark" stays sticky on <html> while the light
stylesheet is the active bundle.
- Light-fill panel text-color safety net (style.scss). Pairs with the
bg-flip safety net upstream introduced in 2707c0546. The bg-flip only
fires in dark mode; this rule fires in both modes and pins text
inside inline-styled light-fill cards (tito/modules.qmd, tito/data.qmd,
etc.) to #1e293b regardless of what --bs-body-color resolves to.
Without it, cards stayed light-fill in the hybrid state but text
inherited the dark-palette light body color = invisible. The matching
!important `color: #e6e6e6` line in dark-mode.scss flips back when
the card flips to #2d2d2d.
- Code blocks inside cards. The previously-merged
`pre code { color: #e6e6e6 }` rule was painting plain (no-language)
fenced blocks light grey on the light card surface — visible on the
box-drawing console output blocks under "Understanding the Export
Process" on tito/modules.qmd. Nest a `pre code, code` override inside
the safety-net selector list so card code is dark in light/hybrid and
light in true dark mode.
- Scope existing global h3 + pre code overrides to [data-bs-theme="dark"].
Both rules were left unscoped previously to compensate for the hybrid
state. The card safety net above now handles hybrid for cards, so the
global rules can be properly scoped — fixes the "### Milestone
Achievements: `tito milestone status`" h3 on tito/data.qmd which was
rendering #d0d0d0 on white in true light mode.
- Table zebra-stripe override (style.scss). shared/styles/partials/_tables.scss
sets the even-row bg to #fafbfc unconditionally; on the dark body the
light text inheriting from --bs-body-color was invisible against the
light row stripe. Add a [data-bs-theme="dark"]-scoped rule using a
subtle white-overlay rgba so striping survives without hard-coding
a specific dark hue.
Light mode unchanged on every page that doesn't use inline-styled cards.
Map inline 700/600 Material accent text to 400-shade variants for WCAG on
#2d2d2d surfaces; add linear-gradient(e3f2fd...) panel rule missed by
solid background hex selectors.
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).
Three small follow-ups on top of the recent dark-mode UX work
(#1529 / #1532-style fixes already on dev):
- _quarto.yml: split `highlight-style: github` into
`light: github` / `dark: github-dark` so code blocks pick up
proper dark theme tokens instead of the light theme over a
dark surface.
- style.scss: pin .who-card paragraphs to #475569 (slate-500)
so they stay readable on the #fafafa card surface even when
the page is in the hybrid state where data-bs-theme="dark"
is set on <html> but the light stylesheet is active — body
color flips to #dee2e6 in that case and inheriting it
invisibly bleached the cards. Also add the global
`#quarto-content h3 { color: #d0d0d0 !important }` and
`pre code { color: #e6e6e6 }` overrides so subheadings and
code text remain readable in dark mode (h3 here is needed
because Quarto re-loads the light bundle as
quarto-color-scheme-extra after the dark bundle, so equal-
specificity rules from _headers.scss otherwise win).
- dark-mode.scss: pair the .who-card paragraph fix above —
when the card flips to #2d2d2d in dark mode, paragraphs
go to #e6e6e6 to match.
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.
Quarto's default styles set
div.sourceCode { background: rgba(233, 236, 239, 0.65) }
on every code block — a LIGHT fill at 65% opacity. Over the dark body
(#1a1a1a) that blends to a washed-out medium grey (~#a0a0a0) which
fights the syntax-highlighted foreground and makes code hard to read.
Override in dark-mode.scss with an explicit dark surface slightly
lighter than the body so blocks read as distinct rectangles, plus a
1px border using $border-color-dark for clean delineation.
Inline code (`tinytorch/`-style spans in prose) had the same washed-grey
problem from the same rgba-light pattern. Switched to a translucent
slate (rgba(110, 118, 129, 0.35)) with light text (#e6edf3) — keeps it
visually distinct from surrounding prose without competing with full
code blocks.
Verified locally on getting-started.html (the page with the most
visible code blocks). Computed bg now rgb(34, 38, 44) = #22262c with
border #454d55, body bg unchanged at #1a1a1a.
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.
Adds a small amber pill below the existing "A Build-It-Yourself
Companion to..." subtitle showing "🔥 TinyTorch v0.1.10 →", linked to
the GitHub Releases page filtered for tinytorch tags.
Why: the previous sidebar had no persistent version indicator, and
the announcement-bar approach was rejected (see config/announcement.yml
header note: "Release news belongs in a changelog, not in the always-
visible nav bar"). The sidebar subtitle area is the natural home for
this kind of meta-info — sticky on desktop, not competing with content,
and follows the existing JS injection pattern.
Design choices:
- "🔥 TinyTorch" prefix + visual divider above the pill prevent the
reader from parsing "v0.1.10" as the textbook's version (which
would be wrong — the textbook is versioned by Volume).
- Amber border + amber text + faint amber background match the
TinyTorch brand color used throughout the announcement bar and
accent system.
- target="_blank" + rel="noopener" — the chip leaves the docs site,
so external-link semantics apply.
- !important on color rules because Quarto's link styles otherwise
win at higher specificity (matches the existing `.sidebar-subtitle
a:hover` pattern in this file).
Version source: hardcoded as "v0.1.10" with a TINYTORCH_VERSION_CHIP
sed marker. The tinytorch-publish-live workflow's UPDATE_VERSION step
already syncs 6 files (pyproject.toml, settings.ini, install.sh,
announcement, README badge, init); adding this file to that step is
a follow-up. For now, manual updates on each release.
Verified in Playwright on index + tito/milestones, light + dark mode.
Computed color rgb(212, 116, 12) light / rgb(245, 158, 11) dark; href
points to releases?q=tinytorch as intended.
#1529 fixed dark-mode contrast on preface.qmd by refactoring inline
style="background: #..." panels to .who-card / .callout-note. The
remaining 200+ inline-styled panels across other pages (big-picture,
index, tito/*, datasets, etc.) were still failing in dark mode — the
fix worked for one page but the user-visible experience was patchwork.
Two structural gaps closed:
1. Sidebar had zero dark-mode coverage. dark-mode.scss declared
$sidebar-bg-dark = #212529 but never applied it to a selector,
and shared/styles/partials/_sidebar.scss hardcodes #495057 link
text against an implicit white surface. Result: white sidebar
visible on every page in dark mode. Fixed by adding rules for
#quarto-sidebar, .sidebar-navigation, sidebar items, section
headers, and dividers — uses the existing $sidebar-bg-dark and
$border-color-dark variables instead of leaving them dead.
2. Inline-style panels site-wide. Cataloged the 14 light-fill hex
values that appear with `background: #X` across the .qmd corpus
(counts in the SCSS comments) and added a [style*=...] attribute
selector layer that flips them to #2d2d2d in dark mode, plus the
8 mid/dark-grey text colors used inline that fail when their
surface flips. !important is required because inline style= beats
class specificity. Decorative dark/saturated fills (#263238,
#0f172a, button blues/oranges, gradient banners) are deliberately
excluded — they render correctly in both modes.
Plus: thin 1px border on .who-card in dark mode for delineation
against the body bg ($body-bg-dark = #1a1a1a vs card #2d2d2d).
Verified across index, big-picture, and tito/milestones in Playwright
with colorScheme: 'dark' (uses Quarto's prefers-color-scheme initial
toggle path, not just data-bs-theme attribute setting). All measured
contrast ratios >= 11.0 WCAG AA. The defensive layer is a transitional
bridge — long-term, individual pages should be refactored to .who-card
/ .callout-note like preface and tito/milestones already are.
Same failure mode flagged in #1529 preface refactor: inline
style="background: #f8f9fa..." beats CSS class specificity, so
dark-mode rules never apply. Five light-fill panels affected:
- Quick Start workflow (#f8f9fa) -> .callout-note
- Discover Milestones card (#e3f2fd) -> .who-card + #2196f3 border
- Learn About card (#fff3e0) -> .who-card + #ff9800 border
- Run Milestones card (#f3e5f5) -> .who-card + #9c27b0 border
- Track Progress card (#f0fdf4) -> .who-card + #22c55e border
- Three Tracking Systems (#f8f9fa) -> .callout-note
- Next Steps CTA panel (#f8f9fa) -> .who-card
Hero gradient banner (lines 5-7), accent border-lefts on the four
command cards, and the two CTA buttons retain inline style — they are
mode-invariant decorative accents (gradient + white text + colored
buttons render correctly in both modes), matching the preface fix.
TinyTorch quarto site is HTML-only (no PDF format in _quarto.yml),
so no when-format gating needed.
Welcome page and several adjacent surfaces had dark-on-dark text in dark
mode after the v0.1.10 release. Two root causes:
1. preface.qmd used inline `style="background: #..."` divs for the
"Why does this matter?" callout, the MLSysBook/TinyTorch comparison,
and the "Who This Is For" persona grid. Inline styles beat CSS
class specificity, so dark-mode rules were ignored.
2. dark-mode.scss had no overrides for several components defined in
style.scss with hardcoded light colors: .comparison-title, the
.tier-{foundation,architecture,optimization,olympics} cards, the
.milestone-card family, .ml-timeline-tech, .preview-badge, and the
callout-body / callout-content text-color cascade.
Changes:
- Refactor the three preface.qmd blocks to use existing .callout-note
and .who-card / .who-grid classes (kept colored left-borders inline
since they are mode-invariant accents).
- Append dark-mode rules covering every selector identified above.
Mirrors the .callout-body !important cascade pattern from
shared/styles/_ecosystem-base-dark.scss:577-584.
PDF branches (when-format="pdf") untouched. Light mode unchanged.
Two related fixes that landed together during a UX walkthrough.
1. H2–H6 decoration override was dropped in a merge conflict.
PR #1524 added an override in tinytorch/quarto/assets/styles/style.scss
that stripped the shared /partials/_headers.scss L-shape decoration
(thick accent left-border + thin accent bottom line) from H2–H6 on
TinyTorch only. The override disappeared at some point between that
merge and today — every H3 on a TinyTorch page is currently rendering
with `border-left: 4px solid #d4740c` + `border-bottom: 1px solid
rgba(212, 116, 12, .25)`. Restoring the override with `!important`
so it survives future shared-partial additions. Scoped to TinyTorch;
book/kits/labs/mlsysim keep their decoration.
2. Comparison-grid "Traditional ML Education" / "TinyTorch: Build →
Use → Reflect" titles converted from H3 to a styled <span>.
Problem: H3 at 24.65px with the accent L-shape reads as a page
heading jammed into a card — awkward scale, awkward hierarchy
(the whole card IS the content; the title isn't a separate
sub-section). Solution: use a `.comparison-title` span class
at 1.15rem (~18.4px), 600 weight, no border — properly card-
scaled, and no heading semantics pollute the doc outline / TOC.
Markup changed from `### Title {.unnumbered}` to
`[Title]{.comparison-title}`.
Verified via Playwright on `http://localhost:4123/`:
- No H3 exists inside `.comparison-bad` / `.comparison-good` now.
- New `.comparison-title` span renders at `font-size: 19.55px`,
`border-left: 0`, `border-bottom: 0`.
- Applied screenshot: /tmp/banner-work/compare-fixed.png shows the
card titles as clean bold text, no underline, no accent bar.
Font audit (same walk): body Inter 17px/25.5px, H1 42.5px/700,
H2 28.05px/600, H3 24.65px/600, code JetBrains-Mono 14.9px, sidebar
15.7px, TOC 15.3px. All consistent with the ecosystem font stack and
reasonable in isolation — no additional font changes needed.
Round-2 UX polish pass after a full Playwright walkthrough surfaced a few
cheap, high-impact wins. Scoped to three files.
HOME (index.qmd)
- Hero hierarchy swap. The prior markup rendered a 2.5rem <p> "Build
Your Own ML Framework" followed by an <h2> "Don't import it.
Build it." — which flipped the semantic hierarchy: the tagline
subtitle read as the most important element, and the memorable
slogan (which matches the pagetitle) read as secondary.
Fix: "Don't import it. Build it." is now the page's h1; "Build your
own ML framework — from tensors to systems." is the subtitle below
it. Screen readers, search engines, and the eye all agree now.
- Preview badge: "Classroom ready 2026" -> "Classroom ready Fall 2026".
The date is now unambiguous (we're in 2026; old copy read as "not
yet shipped in 2026" or "already shipped in 2026" depending on
reader).
- Star-count CTA copy: was "⭐ 23,763 learners · every ⭐ helps
support free ML education". Problem: the dynamic number is the
GitHub stars count, not a learner count — conflating the two is
misleading. Rewrite: "⭐ 23,763 stars on GitHub — add yours and
support free ML education". Concrete number, concrete verb, honest.
MILESTONES HUB (milestones/index.qmd)
- Add a six-card roster at the top showing 1958 -> 2018 at a glance
(Perceptron, XOR Crisis, MLP Revival, CNN Revolution, Transformers,
MLPerf). Previously the hub opened with two prose paragraphs before
the journey table; a first-time reader had to scroll past them to
see the milestone list. The 6-card grid makes the arc instantly
legible; the detailed per-milestone journey table stays in place
further down for the reader who wants module-by-module dependencies.
- Cards are links, each to the milestone's own page.
- Color coding mirrors the tier that produces the milestone's modules:
Foundation (blue), Architecture (purple), Optimization (orange).
CSS (tinytorch/quarto/assets/styles/style.scss)
- New .milestone-grid + .milestone-card classes, styled to match the
preface audience-card aesthetic shipped in the previous polish PR
(neutral #fafafa fill, colored left-border carrying the tier
identity). Responsive: 3-col desktop, 2-col tablet, 1-col mobile.
- data-era="{foundation|architecture|optimization}" attribute on each
card drives the border-left color via the attribute selector, so
the era -> color mapping stays declarative and doesn't need per-card
inline style.
Verified (Playwright against local quarto preview):
- Home h1 is now "Don't import it. Build it." at 42.5px; badge reads
"Preview · Classroom ready Fall 2026"; star link reads "⭐ {N}
stars on GitHub — add yours and support free ML education"
- Milestones hub renders the 6-card grid with correct data-era colors
(foundation = rgb(25, 118, 210), architecture = rgb(123, 31, 162),
optimization = rgb(245, 124, 0)).
Deferred — acknowledged as valid observations in the UX walkthrough but
out of scope for this PR:
- Swap module-page action cards above Module Info (touches ~20 module
files; wants a template-level change, not ad-hoc QMD rewrites).
- Sticky per-module progress indicator (wants JS + scroll listener).
- Announcement-bar collapse on narrow viewport (JS + cross-site).
- Olympics "Coming Soon" -> dated promise (intentionally left alone:
the real Olympics launch content is landing in a separate PR in
the next few days).
cards + header decoration + PDF milestone transitions
Polishes several rough edges in the TinyTorch site surfaced by a visual
walkthrough. Six independent fixes in one PR because they all landed on
the same mental pass:
HTML SIDEBAR
- Rename two sections so their titles don't wrap on the 250px sidebar:
"Capstone Competition" -> "Capstone"
"TITO CLI Reference" -> "TITO CLI"
(navbar link "TITO CLI Reference" -> "TITO CLI" too, for
consistency)
- Remove all three milestone sections ("Foundation Milestones",
"Architecture Milestones", "Optimization Milestones") from the HTML
sidebar. They interleaved between tiers and broke the
Foundation -> Architecture -> Optimization -> Capstone flow the
sidebar is meant to communicate. Milestones stay fully accessible
via the navbar's "Historical Milestones" entry, and the PDF build
(which has its own _quarto.yml) is untouched -- interleaved
milestones are the correct reading experience in print.
- YAML comment added where the milestone sections used to live so a
future contributor knows the removal was intentional.
SIDEBAR SCROLL
- shared/styles/partials/_sidebar.scss: add
`overscroll-behavior: contain` to #quarto-sidebar and
.sidebar-navigation. Before: hovering-and-scrolling over the sidebar
chained the scroll to the body the moment the sidebar hit a
boundary -- so scrolling the sidebar felt like it was never actually
engaging. After: the sidebar's scroll stays in the sidebar.
- Single-source-of-truth win: this improves every Quarto site in the
ecosystem (book/kits/labs/mlsysim/tinytorch/site), not just tinytorch.
H2 L-SHAPE DECORATION (TINYTORCH ONLY)
- shared/styles/partials/_headers.scss decorates H2-H6 with a thick
accent left-border + thin accent bottom line -- an "L-shape" that
reads well in long-form textbook prose. For tinytorch (framework
docs with code blocks, comparison grids, card-based layouts) the
decoration felt heavy and competed with the content itself.
- tinytorch/quarto/assets/styles/style.scss: add a local override
that strips border-left/border-bottom/padding-left/padding-bottom
from H2-H6. Scoped to tinytorch -- book/kits/labs/mlsysim keep the
decoration.
TIER CARDS
- index.qmd's .tier-foundation / .tier-architecture /
.tier-optimization / .tier-olympics cards used four different
gradient fills (blue/purple/orange/pink). Visually loud; fought
the comparison grid and hero on the same page; tier-optimization
read as specifically orange-heavy.
- Flatten to the same neutral #fafafa fill the .audience-card and
preface.qmd cards use, with just a 4px colored left-border carrying
the tier's identity. Each tier still has its distinct color cue;
the page calms down.
PDF NARRATIVE TRANSITIONS
Milestones appeared suddenly in the PDF when a tier ended. Readers
lost context for why they were there and which just-built modules
they were about to exercise. Six short transition paragraphs added
via the narrative-flow-analyzer subagent:
modules/08_training.qmd forward-hook into Foundation Milestones
modules/13_transformers.qmd forward-hook into Architecture Milestones
modules/19_benchmarking.qmd forward-hook into Optimization Milestone
milestones/01_perceptron.qmd tier-components open
(Tensor/Linear/BCELoss/SGD/Trainer)
milestones/04_cnn.qmd first-Architecture-Milestone framing +
three-tier arc explanation
milestones/06_mlperf.qmd sole-Optimization-Milestone +
"third act" framing
Files left as-is because the transitions were already good:
milestones/index.qmd, milestones/02_xor.qmd, milestones/03_mlp.qmd,
milestones/05_transformer.qmd.
DRIVE-BY FIX
modules/13_transformers.qmd had four lines of pre-existing corrupted
trailing content after the last callout (duplicate sentence,
orphan "44B parameters |" table row, orphan Capstone row). Removed
since this PR was already editing the file.
Verification (Playwright against local preview):
- Sidebar section labels: ["Getting Started", "Foundation Tier",
"Architecture Tier", "Optimization Tier", "Capstone",
"Conclusion", "TITO CLI", "Reference", "Community"] -- no
wrapping, no milestones.
- #quarto-sidebar overscroll-behavior: "contain"
- H2 "Don't import it. Build it." computed border-left-width: 0px,
border-bottom-width: 0px, padding-left: 0px
- .tier-card backgrounds: all rgb(250, 250, 250);
border-lefts: 4px solid {tier-color} each.
The TinyTorch announcement bar was reverted during the v0.1.10 publish
merge on 2026-04-22 (commit 0009f55a9) from the 4-line ecosystem template
shipped in PR #1505 back to a single-line release notice:
🎉 v0.1.10 released — v0.1.10 (retry after TINYTORCH_SITE path fix) · See release →
Three problems with the release-notice form:
1. Single-line + type: info breaks visual consistency with the other
eight Quarto announcement bars (all type: primary, 4 lines).
2. Copy reads like a commit message ("retry after TINYTORCH_SITE path
fix") — internal engineering language in always-visible nav copy.
3. Release news persists long after the release — "v0.1.10" is
already stale-sounding and will look abandoned when v0.1.11 ships.
Restore to the unified template used by vol1, vol2, kits, labs, mlsysim,
slides, instructors, site, and staffml: identity line + book link +
"Alongside the book:" sibling row (Hardware Kits / MLSys·im / Labs) +
newsletter. TinyTorch is the "build" lens of the curriculum; line 3 omits
TinyTorch itself and lists the three other learner-tool siblings.
Also documents in the file header comments that this reversion happened
so a future release publish doesn't silently overwrite again. If a future
release warrants a top-of-bar mention, the right pattern is an optional
release_note field on the shared schema that auto-expires — not
overwriting the ecosystem-navigation copy.
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.
CI workflows repeated a ~20-line tlmgr install block inline. Consolidate
to two requirements files that work locally and in CI:
pdf/apt-requirements.txt - system packages (librsvg2-bin)
pdf/tex-requirements.txt - 24 TeX packages
New Makefile target 'make install-deps' reads both files, calling
apt-get + tlmgr. Skips sections when the tool is not on PATH (no-op
on macOS, effective on Ubuntu CI).
CI workflows simplified to 'make install-deps && make pdf', matching
local dev exactly. Adding a dependency now means editing one file,
not two.
