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.
Wave 4 editorial content across 20 modules + new glossary back matter:
1. Module opener hooks (20 new 2-3 sentence paragraphs between the
chapter heading and Module Info callout). Every hook LEADS with
the systems angle (memory, bandwidth, arithmetic intensity,
cache, HBM, roofline, KV cache, hardware utilization, etc.) and
connects back to the ML story. Reinforces that this is a lab
guide for ML systems, not an ML-theory textbook.
2. Code-listing captions on substantive code blocks (roughly >10
lines, defines a class/function/algorithm). Populates Quarto's
List of Listings front matter. Combined across F1/F2/L/O
subagent waves: roughly 60 listings now carry
'**Listing N.M — Brief description**' captions.
3. Figure alt-text audit across 20 module diagrams. Most already
carried objective specific alt-text; a handful were rewritten
for precision.
4. Glossary at back matter (tinytorch/quarto/glossary.qmd + registered
in pdf/_quarto.yml). 90 alphabetical entries spanning tensor /
memory / autograd / training / architecture / optimization
terms. One-sentence definitions. Module cross-references where
the term is central. Lab-guide voice, not dictionary.
5. Style discipline: no em-dashes in prose (caption templates
'— Description' are the only exception, required by parser).
All agent outputs and the hand-revised hooks audited for em-dash
use.
6. SVG trailing-newline hygiene: 8 SVGs touched by the Gemini style
audit had lost their trailing newline. Restored per the SVG
file-hygiene rule.
Header rule simplified: double line (0.6pt + 0.3pt flameorange) →
single 0.4pt flameorange!70 rule. Cleaner, quieter, still visible.
Link validation ran across 168 unique URLs in .qmd sources.
3 URLs actually broken (vs 10 that 403 due to HEAD blocks but work
in a browser):
- GPT-2 paper: cloudfront URL deprecated → cdn.openai.com
- PyTorch extending doc: .md → .html
- mlu-explain.github.io/relu/ doesn't exist → neural-networks
CONTRIBUTING.md at blob/main 404s because the file lives on dev;
will resolve on next release merge to main — leaving as-is.
Dense prose pages (module chapters with 400+ word counts) read tight
at Quarto's default linestretch 1.0. Palatino's natural leading is
~1.2× font size, which is crisp but unforgiving for long-session
lab-book reading. A 1.1 bump adds ~10% more line whitespace, landing
at the Stripe Press / Swift Book / Pragmatic Bookshelf sweet spot for
technical body text.
Side-by-side inspection (module 02_activations 'Why ReLU Dominates'
page at 150 DPI): noticeably more breath between lines, paragraph
transitions clearer, eye travels more comfortably. Code blocks and
callouts unaffected (Verbatim + tcolorbox have independent spacing).
Trade-off: page count grows by roughly 8-12 pages across the 350-page
guide. Acceptable at this scale — readability over pagination.
One-line YAML change in format.pdf block.
Audit findings from .claude/_reviews/section-consistency-report.md and
systems-emphasis-report.md:
- Strip leading emoji prefixes from Systems Implication callout titles
across 17 modules. strip-emojis.lua removes them from PDF render
anyway (XeLaTeX + Latin Modern fonts don't cover emoji ranges
cross-platform), so source now matches what ships.
- Remove duplicate trailing '## Get Started' section from modules
10, 11, 13, 14 — copy-paste artifacts.
- Update pdf/_quarto.yml preamble comment: callout conventions
are class + title-word, no emoji prefixes.
- Running headers: verso shows 'Chapter N · Title' on outer-left, recto
shows 'N.M · Section' on outer-right, small caps navy. Wordmark
centered. Page numbers on outer-edge in footer. Follows H&P / CLRS /
Swift Book convention.
- Book-style paragraph typography: parskip=0pt plus 0.5pt, parindent=1.2em.
First-line indent instead of web-style paragraph gaps.
- List of Figures + List of Tables: lof: true / lot: true in YAML front
matter. One page each, makes 350-page guide's figures navigable.
- Callout title convention documented in preamble comment. Six types
keyed off emoji prefix (Check Your Understanding ✅, Systems
Implication ⚡, Historical Context 📚, Exercise 🎯, Pitfall ⚠️,
Checkpoint 🚦). Reuses Quarto's 5 shipped classes; no new LaTeX.
- Makefile self-heal: when Quarto post-render cleanup errors and
leaves the PDF at top-level pdf/ instead of pdf/_build/, detect
and move it to the canonical location.
Two fixes:
1. Critical rendering bug in modules/10_tokenization.qmd: a Python code
block used for inline {python} variable refs was missing its
opening ```{python} fence. Pandoc interpreted the two `#` comments
inside ("# Character tokenizer: vocab 100, dim 512, float32" and
"# BPE tokenizer: vocab 50,000, dim 512, float32") as top-level
markdown headings, which the book class rendered as Chapters 19
and 20 with the prose lines below dumped as plain text.
Restoring the opening fence (with `#| echo: false`) puts the
variable defs back inside a proper code chunk. The inline
{python} tradeoff_char_embed etc. refs in the next paragraph
now resolve correctly.
2. Revert the TOC spacing change from the previous commit. User
confirmed the default book-class TOC leading is already fine;
tocloft bumps made it too airy. arraystretch 1.2 for tables
and enumitem itemsep 0.3em for lists remain — those targeted
visible defects.
PDF typography improvements:
- arraystretch 1.2: every tabular gets ~20% more vertical breathing
room. Previous default of 1.0 packed rows tight enough that
multi-line cells (like the "You'll Have Built" milestone table)
felt cramped.
- enumitem itemsep 0.3em + topsep 0.3em on numbered and bulleted
lists: small air between list items so code-listing-style items
like "19 Character tokenizer..." / "20 BPE tokenizer..." don't
touch each other.
- tocloft cftbeforesecskip 0.3em / cftbeforesubsecskip 0.2em: TOC
section-level entries (32.1, 32.2, ...) no longer stack on tight
leading. Scanning a 30-chapter TOC is easier.
getting-started.qmd:
- Remove "Early Explorer Territory" callout from the top. The
content warned readers about rough edges and pointed to
Summer/Fall 2026 classroom readiness — appropriate during early
drafts but out of place now that the Lab Guide is shipping.
The Prerequisites Check callout remains (different purpose —
tells readers what knowledge they need).
No change to chapter title styling ("Chapter N" eyebrow + huge title)
or header/footer setup — both already match textbook editorial
conventions (see pdf/_quarto.yml lines 321-395).
Pointed-at fixes from a visual PDF review:
- preface.qmd: drop emojis from the astronaut/rocket-scientist opener
(XeLaTeX renders them as zero-width glyphs, leaving phantom space
before the period); split the colored-card grids into HTML-only and
PDF-only branches via :::{.content-visible} so PDF readers get a
clean bold-paragraph layout instead of the divs flattening into
unstyled prose; remove the JIT/Pin compilers footnote.
- modules/04_losses.qmd: blank line before the Case 1/Case 2 bullet
lists so Pandoc actually emits them as a list (not run-on prose),
plus a PDF-only \medskip between the two cases since callouts
collapse paragraph spacing.
- milestones/index.qmd, conclusion.qmd: remove stray --- horizontal
rules in body content (per project rule: HRs only inside code or
style examples).
- assets/images/diagrams/03_layers-diag-1.svg: redraw per STYLE.md.
Old version had four L-shaped paths starting inside the source box.
New version: orange parent at top, three children fanning out below
with straight diagonal/vertical arrows, no overlapping geometry.
- pdf/_quarto.yml:
* fvextra Highlighting/verbatim envs with breaklines so long code
lines wrap cleanly inside the page column instead of overflowing
the right margin.
* \titleformat{\part} so Part divider pages carry the brand: a
flameorange "PART I" eyebrow above a torchnavy bold-sans title,
bracketed by hairline rules.
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).
The tinytorch/site-legacy/ directory was the old Sphinx + Jupyter Book
project. After the Quarto migration:
- Live website builds from tinytorch/quarto/ (project: website)
- Lab Guide PDF builds from tinytorch/quarto/pdf/ (project: book)
- All five tinytorch CI workflows invoke `quarto render` only;
nothing calls jb / jupyter-book / sphinx-build anywhere.
site-legacy/ was kept around as documentation of the previous pipeline
but has zero live consumers (verified: ripgrep across .py/.yml/.yaml/
.sh/.qmd/.md/.json/.toml/.lua/Makefile finds no remaining references
outside the tree itself). 27 MB, 213 files removed.
Guard rails removed alongside the tree:
- .pre-commit-config.yaml: drop tinytorch/site-legacy/ from the
check-internal-links exclusion block (no longer needed).
- tinytorch/quarto/tools/measure-pdf-images.py: drop the
`"site-legacy" in parts` skip from both the source-image index
and the .qmd index (2 occurrences).
- .github/workflows/tinytorch-build-pdfs.yml: drop the "legacy
jupyter-book pipeline ... is retired" historical comment.
- tinytorch/quarto/pdf/_quarto.yml: drop the "Replaces the legacy
jupyter-book + XeLaTeX pipeline" header comment and the
"palette mirrors site-legacy/_config_pdf.yml" note (the Quarto
config is now the canonical source for the brand palette).
Documentation cleanup:
- shared/styles/BRAND.md: repoint the broken
`tinytorch/site/_static/custom.css` reference at the live Quarto
SCSS files (style.scss + dark-mode.scss).
Quarto is now the sole TinyTorch publishing engine.
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/.
