Two HTML-output bugs affecting every algorithm block across both volumes:
1. pseudocode.js init ran synchronously at parse time, but the book loads
MathJax with `defer` and no KaTeX, so no math backend existed yet and
renderElement threw "No math backend found" -- leaving raw \begin{algorithm}
LaTeX on the page (reproduced on the live site). Wait for MathJax startup
(or KaTeX) before rendering.
2. The rendered .pseudocode-container had no overflow handling, so a wide
algorithm line forced page-level horizontal scroll. Scope overflow-x: auto
to the container so it scrolls in its own box, matching the wide-table rule.
Quarto emits every pipe table as \longtable, which runs LaTeX's output
routine to page-break and therefore escapes any tcolorbox callout: the box
closes early and the table + trailing content render unframed (the 'broken
callout' symptom in tall worked-example callouts).
Inside our callouts (new flag \ifmfxInCallout, set by the fbx/fbxSimple
environments) \longtable is redefined to a plain non-breaking tabular
confined to the box. The shim matches Pandoc's fixed longtable shape:
redirects \caption/\label, swallows the caption-row \tabularnewline, gobbles
the repeated header and foot scaffolding (\endfirsthead..\endlastfoot), and
adds a closing rule. Captioned tables re-emit via \captionof{table} + the
saved label so cross-references still resolve. Body (non-callout) longtables
are untouched and still page-break normally.
Verified on full vol1: all 41 in-callout tables now render framed inside
their boxes (Lighthouse, Napkin Math 2.8, mixed-precision FP/BF16, ...);
0 unresolved cross-refs; margin oracle unchanged; no LaTeX warnings.
Known cosmetic: in-callout captions render below the table (vs above).
Introduce 13 LaTeX-typeset algorithm blocks across 8 chapters (Adam update,
gradient checkpointing, FlashAttention, backpropagation, mini-batch SGD,
reverse-mode AD, PTQ calibration, tiled GEMM, ring all-reduce, 1F1B pipeline,
continuous-batching scheduler, speculative decoding, power-of-two routing),
each integrated into existing prose with a motivating lead-in and a
systems-consequence follow-up.
Extension (book/quarto/_extensions/mlsysbook-ext/pseudocode):
- Vendored under the owned mlsysbook-ext/ namespace (moved from leovan/,
version -mlsysbook-custom) and wired into the html, pdf, and epub filters.
- MIT Press cross-ref casing: @algo- -> 'algorithm N' mid-sentence,
@Algo- -> 'Algorithm N' at sentence start.
- Right-aligned italic triangle comments (CLRS column convention).
- Static EPUB renderer (upstream supports only HTML via pseudocode.js and PDF
via algpseudocodex; EPUB previously emitted raw \begin{algorithm}).
- Uses the algo- prefix: native @alg- collides with Quarto's algorithm theorem
environment and FATALs the build.
Ref tooling (book/cli/commands): teach validate.py, bib.py, and info.py the
algo-/Algo- crossref prefix (LABEL_REF_PATTERN, EXCLUDED_CITATION_PREFIXES,
Algorithm label-def patterns, and a chunk-option label harvest that runs inside
the pseudocode fence) so check refs and check labels resolve @algo-/@Algo-
instead of misreading them as missing citations.
Verified rendering in HTML, PDF, and EPUB; check refs and check labels pass
book-wide.
Vendor leovan/quarto-pseudocode into _extensions, patched for the book:
@algo-/@Algo- references render lowercase/capitalized per MIT Press style,
and algorithm comments default to a triangle marker in italics. Register
the filter in the shared HTML and PDF filter chains. Algorithm block
conversions in chapter prose follow in separate commits.
Reframe the post-render script as a designed resolution step of the
website-mode pipeline rather than a "fix" for broken output. Extend it
to handle the previously-unresolved `Principle \ref{pri-X}` pattern:
Pandoc parses bare `\ref{}` as inline math, MathJax renders the
undefined label as `???`, leaving Principle ??? leaks in the HTML.
Pattern 4 detects `<span class="math inline">\(\ref{pri-X}\)</span>`
and substitutes the resolved `Principle N` link by replaying the
per-volume principle-callout count across parts/*_principles.qmd in
declared order. Cross-volume independent numbering.
Supporting changes:
- Add a Math handler to the custom-numbered-blocks Lua filter as a
conceptually-correct sibling to the existing RawInline handler.
Benign no-op cross-file (data isn't populated); lights up
automatically if the principles file is ever in the same Pandoc
invocation as the chapter that references it.
- Propagate the rename to epub_postprocess.py import, verify_rendered_xrefs.py
doc strings, scripts/README.md, and validate.py mention.
- Rename function fix_cross_references → resolve_cross_references.
foldbox.css and foldbox.lua both used @media (prefers-color-scheme: dark)
as the sole dark mode mechanism. This only activates on OS-level preference
and ignores Quarto's manual toggle button (which adds body.quarto-dark).
Result: toggling dark mode via the site button left all callout boxes
(Learning Objectives, Quiz, Checkpoint, etc.) rendering with light-mode
colors -- near-white summary text on a white background, invisible to
the reader.
Fix: emit both mechanisms in parallel.
- foldbox.css: duplicate structural rules under body.quarto-dark selectors
- foldbox.lua: refactor generateDarkModeCSS() to emit @media block plus
a body.quarto-dark block via a shared emitCalloutRules() helper
Fixes callout rendering for all toggle-based dark mode users.
The YAML config declares principle as scope: global ("book-wide:
Principle 1, 2, 3..."), but the Lua filter only honored half of that:
prefix was cleared so labels rendered without a chapter number, but
the counter still reset at every file's H1 boundary, so every part
got Principle 1, 2... independently. The conclusion's
@tbl-twelve-principles and (Principle \ref{pri-...}) prose all
silently expected real global numbering.
Three coordinated changes in custom-numbered-blocks.lua:
- New seed_global_counters() walks book.render in order, reads each
prior chapter file, counts class occurrences via regex, and seeds
fbx.counter[cntname] so the first callout in this file gets the
correct cumulative number.
- Meta_initClassDefaults populates fbx.global_scoped_groups (any
class whose group has scope: global) and calls the seeding
function.
- Pandoc_prefix_count's H1 reset now skips global-scoped counters
via is_global_scoped_cntname() helper so they accumulate across
the whole book instead of zeroing per file.
Also converts the only hand-typed competing reference in the book:
nn_architectures.qmd:381 had "(Invariant 6)" hard-coded. Replaced
with (Principle \ref{pri-arithmetic-intensity}) so the auto-numbering
is canonical everywhere.
Verified offline against vol1 render order: foundations -> 1,2;
build -> 3,4; optimize -> 5-8; deploy -> 9-13. Matches what the
conclusion's "(invariants 3-4 / 5-8 / 9-12)" framing assumes (with
pri-bias-feedback as #13, addressed in a follow-up branch).
To take effect, delete the stale xref JSON before the next render:
rm -f book/quarto/_pdfbook_xref.json book/quarto/_htmlbook_xref.json
Native Quarto callouts (.callout-tip used for Learning Objectives,
.callout-note, etc.) have three sources of visible blank space that
make them look inconsistent with custom foldbox callouts (Napkin Math,
War Story, Example, etc.) across the book:
1. Bootstrap's '.callout-body > :first-child { padding-top: .5rem }'
stacks on top of the body container's own padding-top, producing a
visible gap when the body starts with a <ul>.
2. '.callout-icon-container' and '.callout-title-container' carry
'padding-bottom: 1em' from Quarto's own stylesheet, making the
header 17px taller than a foldbox <summary>.
3. '.callout .callout-body' in _base-styles.scss sets padding-top to
0.75rem; foldbox.css sets its body padding-top to 0.5rem.
Fix, all in foldbox.css (the canonical home for callout geometry):
- Add a :first-child rule symmetric to the existing :last-child rule,
zeroing margin-top and padding-top.
- Zero padding-bottom on .callout-header > .callout-icon-container and
.callout-title-container for native callouts.
In _base-styles.scss:
- Reduce .callout .callout-body padding-top from 0.75rem to 0.5rem to
match foldbox's body padding.
Verified via Playwright measurement: Learning Objectives header height
now 37.17px (was 54.17px), body padding-top 8.5px (was 12.75px), exactly
matching Napkin Math foldbox summary (36.88px / 8.5px).
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.
The initial half-title implementation hooked \halftitle into the
redefined \frontmatter macro in tex/header-includes.tex, which meant
the half-title printed at the very start of the front matter, BEFORE
the Quarto titlepage extension's coverpage block. The resulting PDF
sequence was half-title -> cover art -> title page, which is backwards
from the standard academic book sequence.
The Quarto titlepage extension is local to this repo at
_extensions/mlsysbook-ext/titlepage/before-body.tex. Rather than
fighting the upstream extension, edit the local copy to add a
\halftitle injection point at the seam between the coverpage block
and the titlepage block. This produces the standard sequence:
page 1 cover art (dust-jacket style, rendered by Quarto coverpage)
page 2 half-title (rendered by \halftitle defined per volume)
page 3 blank verso
page 4 title page (rendered by Quarto titlepage extension)
Revert the \frontmatter redefinition in tex/header-includes.tex to its
original form (no longer calls \halftitle — the extension template
calls it directly). Keep the \providecommand{\halftitle}{} default so
the extension's \halftitle call is a no-op when no per-volume half-
title file is loaded.
Update the header comments in tex/halftitle-vol1.tex and
tex/halftitle-vol2.tex to describe the new injection point accurately.
Verified by smoke build of vol1 and vol2 dedication-only PDFs, visual
inspection of pages 1-4 in each:
- Vol1: Harvard crimson half-title, sequence cover -> half-title
-> blank -> title, dedication still centered via TikZ
- Vol2: ETH Zurich blue half-title, same sequence, dedication still
centered via TikZ
Standardize table formatting across 25 README files to use
HTML tables with consistent styling (thead/tbody, column widths,
bold labels) matching the main README's presentation.
Use a file watcher to detect when the PDF is created/modified during
build, then automatically open it in VS Code. Build still runs in the
visible terminal so users see progress. Also fix LaTeX comma-in-title
bug in foldbox.tex by bracing the title argument inside tcolorbox options.
- Rewrite notation chapter with collision-resolution rationale and quick-reference table
- Fix foldbox.tex page-break spacing (remove forced font size, improve continuation margins)
- Make dropcap.lua robust to RawInline/index entries and non-standard PDF formats
- Add DAM Coordination (sum→max overlap) and Bottleneck Diagnostic table to appendix
- Add Bottleneck Diagnostic table to Part III Optimize principles intro
- Promote Iron Law analogy footnote to callout-perspective box in introduction
- Rename 'Napkin Math' callout labels to cleaner titles in serving/conclusion
- Inline SciPy footnote into figure caption in frameworks chapter
- Add Iron Law production monitoring callout in ops chapter
- Add Sorscher et al. 2022 to references.bib
- Fix TikZ coordinate ordering in training chapter memory chart
- Comment out non-intro chapters in PDF config for focused compilation
- Change vol2 scaling laws callout from callout-note to callout-theorem
Renames "Lighthouse Examples" to "Lighthouse Archetypes" for greater consistency and clarity throughout the book.
This change emphasizes the role of these models as recurring architectural patterns rather than just examples.
Key changes:
- sci() and sci_latex() now convert Pint quantities to base units
(fixes 10^2 showing instead of 10^14 for TFLOPs values)
- Add md_frac(), md_sci(), md_math() helpers for LaTeX in Markdown()
- Update ml_systems.qmd with proper LaTeX fraction rendering
- Add freeze: false to _quarto.yml to prevent caching issues
- Update CLAUDE.md with QMD inline Python conventions
- Fix LATEX_ADJACENT issues across multiple QMD files (Unicode symbols)
Principles are now referenced by their bold-text names (e.g., **The Iron Law**,
**Silicon Contract**) rather than Quarto cross-ref IDs that were not rendering
reliably. This follows the Hennessy and Patterson convention where named laws and
principles are referenced by name throughout the text.
Changes:
- Remove #principle-* div IDs from all four Part opener files
- Remove (@principle-*) parenthetical refs from 16 chapter files
- Remove website-specific xref logic from custom-numbered-blocks Lua filter
- Update ml_systems.qmd Python variable references for consistency
Major additions to hw_acceleration (Fallacies & Pitfalls, new sections).
Remove stale appendix_historical (content migrated to DAM-aligned appendices).
Minor fixes across multiple chapters (notebook-link classes, cross-references).
Update custom-numbered-blocks Lua filter and LaTeX header includes.
- Rename callout-takeaway → callout-takeaways across all 6 config files,
style.scss, epub.css, icon files, and 34+ content files
- Revert Fallacies & Pitfalls from callout/header experiments back to
bold inline format: **Fallacy:** ***statement***
- Increase post-colon spacing in all callout labels: em-space in HTML
(foldbox.lua), \hspace{0.5em} in PDF (foldbox.tex)
Create a new callout type with deep indigo color scheme (#3D3B8E)
for the enduring principles that open each Part. Add full support
across HTML (foldbox.css, style.scss), dark mode (dark-mode.scss,
foldbox.css @media), EPUB (epub.css), and PDF (YAML configs for
all 4 build targets). Include pillar icon in SVG/PNG/PDF formats.
Migrate all 9 principles QMD files from .callout-note to the new
.callout-principle class.
14 editorial improvements to Chapter 1 (ML System Architecture):
- Add lead-in paragraph after Learning Objectives
- Fold Deployment Paradigm Foundations into Framework section
- Rename Lighthouse callout to "Five Reference Workloads"
- Change "throughout this volume" to "throughout this book"
- Move Distributed Intelligence Spectrum figure earlier (near paradigm overview)
- Reformat System Balance Across Paradigms table with proper grid rows
- Add progressive Lighthouse model descriptions with systems context
- Differentiate Deployment Spectrum (Conceptual) vs Hardware Spectrum (Concrete)
- Differentiate callout-definition (teal) from callout-notebook (blue) in CSS
- Add fig-pos="t" to Edge Device figure; standardize all figures to top placement
- Add @fig-mlsys-playbook-flowchart cross-reference to decision framework prose
- Remove premature Federated/Collaborative Learning from Pattern Selection Guide
- Tighten all 7 Fallacies and Pitfalls to single focused paragraphs
- Update cross-references from removed section ID to parent section
Add new custom callout type for checkpoint/milestone moments in chapters.
Includes bronze (#CD7F32) color theme, SVG/PNG/PDF icons, and full support for:
- Light mode (foldbox.css)
- Dark mode (foldbox.css @media, dark-mode.scss)
- EPUB format (epub.css)
- All Quarto config files (HTML, PDF, EPUB for both volumes)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Add new "Systems Perspective" callout type for deep engineering insights:
- Create lens+gear SVG/PNG icon representing "looking deeper at systems"
- Use deep slate color (#4A5568) to convey wisdom and gravitas
- Add CSS styles for light and dark modes
- Configure perspective group and class in all quarto configs
This callout is part of the "Deep Trio" pedagogical structure:
- Lighthouse: recurring example models (context)
- Perspective: engineering truth/physics (theory)
- Notebook: hands-on math/code (practice)
Label: "Systems Perspective"
Add new Lighthouse callout type for recurring example architectures:
- Create SVG/PNG icons with golden amber theme (#B8860B)
- Add CSS styles for light and dark modes in foldbox.css
- Configure lighthouse group and class in all quarto configs
Fix existing callout icon issues:
- resource_slides: change from green to teal (#20B2AA), redesign as presentation
- resource_videos: change from gold to teal (#20B2AA) for consistency
- notebook: replace <text> element with path-based Sigma for cross-platform rendering
The whitespace cleanup in 853eb03ee removed trailing blank lines from
_titlepage.tex and before-body.tex. This caused \end{titlepage} to be
placed on the same line as a %%% comment, making LaTeX treat it as
part of the comment and skip it entirely.
This resulted in: LaTeX Error: \begin{titlepage} on input line 380
ended by \end{document}
Also excludes titlepage .tex files from end-of-file-fixer hook since
they require trailing blank lines for proper template concatenation.
* Restructure: Move book content to book/ subdirectory
- Move quarto/ → book/quarto/
- Move cli/ → book/cli/
- Move docker/ → book/docker/
- Move socratiQ/ → book/socratiQ/
- Move tools/ → book/tools/
- Move scripts/ → book/scripts/
- Move config/ → book/config/
- Move docs/ → book/docs/
- Move binder → book/binder
Git history fully preserved for all moved files.
Part of repository restructuring to support MLSysBook + TinyTorch.
Pre-commit hooks bypassed for this commit as paths need updating.
* Update pre-commit hooks for book/ subdirectory
- Update all quarto/ paths to book/quarto/
- Update all tools/ paths to book/tools/
- Update config/linting to book/config/linting
- Update project structure checks
Pre-commit hooks will now work with new directory structure.
* Update .gitignore for book/ subdirectory structure
- Update quarto/ paths to book/quarto/
- Update assets/ paths to book/quarto/assets/
- Maintain all existing ignore patterns
* Update GitHub workflows for book/ subdirectory
- Update all quarto/ paths to book/quarto/
- Update cli/ paths to book/cli/
- Update tools/ paths to book/tools/
- Update docker/ paths to book/docker/
- Update config/ paths to book/config/
- Maintain all workflow functionality
* Update CLI config to support book/ subdirectory
- Check for book/quarto/ path first
- Fall back to quarto/ for backward compatibility
- Maintain full CLI functionality
* Create new root and book READMEs for dual structure
- Add comprehensive root README explaining both projects
- Create book-specific README with quick start guide
- Document repository structure and navigation
- Prepare for TinyTorch integration
