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 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.
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 7 tinytorch/milestones/*/ABOUT.md files contained unique narrative
content (historical context, "aha moment" stories, prerequisite tables,
runnable instructions) but were stranded after the Jupyter Book retirement
— mystnb format, no Quarto renderer, no entry in any TOC.
Port them into the Lab Guide so the historical recreations finally have a
canonical home that ships with the book PDF and the website.
Layout (Option A — interleaved between tiers):
• Foundation Tier (Modules 01–08)
• Foundation Milestones (1958 Perceptron · 1969 XOR · 1986 MLP)
• Architecture Tier (Modules 09–13)
• Architecture Milestones (1998 CNN · 2017 Transformers)
• Optimization Tier (Modules 14–19)
• Optimization Milestones (2018 MLPerf)
• Capstone (Module 20)
Each milestone unlocks immediately after the modules that power it,
matching the "your code recreates history" pedagogy.
Conversion notes:
• mystnb {tip} blocks → :::{.callout-tip title="…"}
• mystnb admonitions → :::{.callout-note title="…"}
• Added a "Milestone Info" callout per chapter (tier · difficulty ·
time · prerequisites) to mirror the "Module Info" header used by the
module chapters.
• milestones/ABOUT.md became milestones/index.qmd (Part overview) so
the new "Foundation Milestones" Part starts with a landing page that
summarises all six milestones.
Wiring:
• tinytorch/quarto/pdf/_quarto.yml — three new Parts interleaved
between the existing tier Parts; comment explains the placement rule.
• tinytorch/quarto/_quarto.yml — sidebar gets three new sections
("🕰️ Foundation Milestones", etc.) and the navbar gains a top-level
"Historical Milestones" link to the new index.
• tito/milestones.qmd is unchanged: it documents the `tito milestone`
CLI (separate purpose from the new narrative chapters).
Verification:
• make pdf produces TinyTorch-Guide.pdf at 330 pages with all six
milestones at the expected logical positions; confirmed visually
that the "Milestone Info" + "What You'll Learn" callouts render
with proper Quarto styling.
• quarto render produces 7 new pages under _build/milestones/.
• pre-commit run passes (incl. the internal-link validator).
Brings the TinyTorch lab guide's Quarto project in line with
book/quarto/, the only other in-tree Quarto publication that builds
both web and PDF outputs from a single source. The previous name had
three redundancies:
- already under tinytorch/, so "site-" prefix wasn't disambiguating
- also produces the PDF lab guide, so "site-" was misleading
- the top-level site/ dir made "site-quarto" read as "the site's
quarto config" rather than "the tinytorch site, in quarto"
After this rename the convention is straightforward:
book/quarto/ -> the textbook (web + PDF)
tinytorch/quarto/ -> the TinyTorch lab guide (web + PDF)
mlsysim/docs/ -> mlsysim API reference (kept as docs/, since it
really is API reference, not a publication)
Touches 7 GitHub workflows, both .gitignore files, the rename target's
own self-references (Makefile, _quarto.yml configs, STYLE.md,
measure-pdf-images.py), and 6 copies of subscribe-modal.js plus a few
shared scripts/configs whose comments documented the old path.
Verified: rebuilt pdf/TinyTorch-Guide.pdf (2.1M) cleanly from the new
location with 'make pdf' from tinytorch/quarto/.
