Introduces a pre-commit hook to ensure SVG image files are well-formed XML,
preventing potential rendering or processing issues. This leverages `lxml` for
parsing, which has been added as a new dependency.
Corrects missing whitespace between attributes in existing SVG figures to
comply with the new validation requirements.
Normalize book prose/style issues across touched chapters and remove remaining structural warnings so validation output is clean and reproducible in CI. Also tighten inline/times-spacing validation behavior to reduce noisy false positives while preserving strict checks.
Remove redundant ml_ prefix from ml_workflow chapter files and update all
Quarto config references. Consolidate custom scripts into native binder
subcommands and archive obsolete tooling.
Port all custom validation and maintenance scripts into the binder CLI
as native subcommands, eliminating the need for standalone scripts.
New `binder validate` subcommands (10):
- section-ids: verify all headers have {#sec-...} IDs
- forbidden-footnotes: check footnotes in tables/captions/divs
- footnotes: validate footnote refs/defs (undefined, unused, duplicate)
- figure-completeness: check figures have captions and alt-text
- figure-placement: audit figure/table proximity to first reference
- index-placement: check LaTeX \index{} placement
- render-patterns: detect problematic rendering patterns
- dropcap: validate drop cap compatibility
- part-keys: validate \part{key:...} against summaries.yml
- image-refs: validate image references exist on disk
New `binder maintain` subcommands (2):
- section-ids (add/repair/list/remove): full section ID lifecycle
- footnotes (cleanup/reorganize/remove): footnote management
Updated 11 pre-commit hooks to use binder commands instead of scripts.
Updated VSCode extension commands to use binder CLI.
All validators verified against original script output (parity confirmed).
- Run manage_section_ids.py to add 294 missing section IDs and
standardize 62 non-conforming IDs to hierarchy-based format
- Fix 12 double-hash bugs (e.g., -cbb8-cbb8 -> -cbb8) from script
- All cross-references updated to match new IDs (19 refs across files)
- Verified clean: check_unreferenced_labels.py and check_duplicate_labels.py pass
- Add book-verify-section-ids pre-commit hook (runs --verify mode, ~1.5s)
Renamed the core physics engine from to to better align with
the book's title and pedagogical goals.
New features:
- Introduced and classes in and .
- Digital twins now carry their own attributes (bandwidth, FLOPS) and
methods (ridge_point, memory_size).
- Global search and replace updated all 16 chapters to use .
- Maintained backward compatibility for legacy constants during migration.
- Fix broken cross-refs in training.qmd (em-dash parsed as part of ID)
- Remove footnote from table cell in ml_systems.qmd
- Add @tbl- references for 22 unreferenced tables across 5 files
- Comment out stale SVG prevention hook in pre-commit config
- Auto-fixes from bibtex-tidy, blank-line collapse, pipe-table prettify
Add proper equation labels ({#eq-...}) and prose references (@eq-...)
to 138 equations across 15 Volume 1 chapters following the gold-standard
pattern from serving.qmd.
Key changes:
- Label all display math equations with {#eq-kebab-case-name}
- Add @eq-name references in prose before each equation
- Equations include: Iron Law, Amdahl's Law, Roofline Model,
activation functions, backpropagation, attention mechanisms,
queuing theory, quantization, and system throughput formulas
Also includes:
- PDF formatting improvements (newpage directives for Vol 2)
- LaTeX header updates for chapter styling
- Pre-commit config and validation script updates
Organizes quantitative calculations into a dedicated `physx` library, for improved code organization and maintainability.
- Moves calculation logic, constants, and formatting helpers.
- Updates chapters to import from the `physx` library.
- Adds pre-commit hooks for inline reference and unit validation.
- Deletes obsolete inline Python calculation validation files.
- Fix \index{} commands breaking rendering when placed before footnote
definitions, div openers (:::), or on same line as headings
- Add check_index_placement.py script with --fix flag to automatically
detect and fix these patterns
- Update training.qmd and data_engineering.qmd with corrected index placement
- Include other pending content and visualization updates
- Fix footnotes incorrectly breaking into definition text (appendix_machine, appendix_algorithm)
- Move forbidden footnotes out of callout divs (hw_acceleration, serving, training)
- Convert inline footnote info to inline text where appropriate
- Add fig-alt text to code-cell figures (dl_primer, hw_acceleration, serving, workflow)
- Add fig-cap and fig-alt to TikZ figures (distributed_training, introduction, edge_intelligence, networking, sustainable_ai)
- Fix hook ordering: Black formatter now runs before blank line collapse
- Move footnote definition outside TikZ div in frameworks.qmd
- Fixes fig-amortization-comparison: scales Y-axis values from 12000 to 12
to avoid LaTeX dimension limit (~16383pt)
- Fixes fig-compute-optimal-frontier: replaces problematic \fill...plot
with proper \addplot[fill=...] \closedcycle for log-scale coordinates
- Updates figure reference text to use @fig-selection-inequality
- Adds ch_data_selection.py calculation module
- Updates viz.py with new plot functions
- Various chapter updates across vol1 and vol2
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)
- Properly preserves left/center/right alignment from grid tables
- Added --check mode for pre-commit warning
- Added book-check-grid-tables hook to warn about grid tables
- Grid tables should be converted to pipe for better inline Python support
- Updated fix_bullet_spacing.py with --check mode for CI validation
- Added book-fix-bullet-spacing hook to auto-fix missing blank lines
before bullet lists during commits
- Script now provides clear error messages with line numbers
Create check_figure_completeness.py pre-commit hook that validates all
figures have captions and alt-text across div, markdown, and code-cell
syntaxes. Add code-cell figure support to extract_figures.py and
figure_table_flow_audit.py. Fix fig-algo-efficiency missing caption in
introduction.qmd and fig-business-cost-curve missing alt-text in ops.qmd.
Vol 1 now passes with 199/199 figures complete.
- Update Quarto config for epub, html, and pdf Vol 1 builds
- Rename data_efficiency chapter to data_selection with updated content
- Edit chapters across Vol 1 and Vol 2 for clarity and consistency
- Add references, glossary updates, and new debug build script
- Update pre-commit config and part intro narratives
- Remove tinytorch-validate-cli-docs hook from pre-commit
- TinyTorch has its own dedicated CLI validation system
- Keep only formatting checks in pre-commit hooks
- Renamed vol2/advanced_intro to vol2/introduction for consistency
- Updated all scripts and configs to use vol1/ instead of core/
- Updated pre-commit config to check all contents/ not just vol1/
- Updated path references in Lua filters, Python scripts, and configs
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.
Updates the codespell pre-commit hook configuration to correctly skip JavaScript files. This prevents false positives and ensures accurate spell checking.
Fix remaining instances where emoji was before the name
(🔥 TinyTorch → Tiny🔥Torch) for consistent branding.
Also add "curren" to codespell ignore list (contributor name).
- Add sphinxsetup configuration with distinct colors for each admonition type
(tip=green, warning=orange, note=blue, caution=red, etc.)
- Convert {admonition} with :class: attribute to native {tip}, {warning},
{seealso} directives for proper Sphinx type detection in LaTeX output
- Remove unsupported emojis from site markdown files for LaTeX compatibility
- Update codespell ignore list for font names (Heros) and PDF options (FitH)
- Update 20 ABOUT.md files and 16 site/*.md files
- Live publish now merges dev into main before building
- Removed auto-trigger on push to main (manual only)
- All build jobs depend on sync completing first
- Ensures public site always reflects tested dev state
- Updated README with improved badges and formatting
- Add clear section headers for Book, TinyTorch, and Repo-wide hooks
- Prefix all hook names with domain tags (e.g., [Book], [Repo])
- Fix SVG prevention hook to only apply to book/ directory
- Fix codespell and list-formatting hooks to scope to book/ only
- Add placeholder section for future TinyTorch hooks with examples
- Move JSON and YAML validation to Repo-wide section
This reorganization prepares for the merged monorepo structure where
book and tinytorch have different validation requirements.
- Update format_tables.py to use workspace-relative path (quarto/contents/)
- Update validate_part_keys.py script to use book/quarto paths
- Scripts in book/tools/ that calculate workspace_root need paths relative to book/
- Other scripts need full book/quarto/contents/ paths
* 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
Replaced external check-json hook with custom validator using Python's
built-in json module (json.load). Created validate_json.py wrapper to
handle multiple files.
Benefits:
- No external dependencies
- Uses Python's standard library json parser
- Same validation logic as the build system
- Fast and reliable (0.16s for all JSON files)
Add new pre-commit hook to validate that all @key citations in .qmd
files have corresponding entries in their .bib files. This catches
missing bibliography entries before they cause Quarto build failures.
Features:
- Validates citations against bibliography files
- Filters out cross-reference labels (fig-, tbl-, sec-, etc.)
- Provides clear error messages with missing citation keys
- Only checks files being committed (not entire codebase)
- Runs in quiet mode to reduce noise
New script: tools/scripts/content/validate_citations.py
Updated: .pre-commit-config.yaml with validate-citations hook
- Validates table alignment (text=left, numbers=right)
- Checks header and first column bolding
- Ensures proper spacing and structure
- Runs on all .qmd files in quarto/contents/
- Exits with code 1 if formatting issues found
Script fixes:
- Fix year header detection to handle both '## 2025' and '## 2025 Updates' formats
- Fix labs organization to work with AI-generated summaries
- Add AI artifact cleanup to remove 'Let me know...' phrases
- Improve lab grouping logic for AI mode
Changelog updates:
- Generate comprehensive changelog with AI summaries for all changes since Aug 6
- 61 files updated: 6 frontmatter, 29 chapters, 26 labs
- Clean, professional AI-generated descriptions without artifacts
- Created check_forbidden_footnotes.py to detect problematic footnote placements
- Checks for footnotes in: table cells, figure/table captions, div blocks (callouts)
- Added to pre-commit config as 'check-forbidden-footnotes' hook
- Fixed false positive detection by requiring table rows to start with |
- Moved XOR footnote in dl_primer.qmd outside callout block
- All 62 .qmd files now pass validation
- Prevents Quarto build failures from footnotes in unsupported locations
Enhances clarity and accuracy of explanations throughout the chapters, focusing on definitions, relationships, and system-level trade-offs. It improves flow and highlights scaling-related bottlenecks.
