Adds newsletter infrastructure: CLI commands (new, list, preview, publish,
fetch, status) integrated into binder, Quarto archive site config for
mlsysbook.ai/newsletter/, and 12-month editorial content plan. Drafts
are gitignored for private local writing; sent newsletters are committed
as the public archive.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Refactors numerous embedded TikZ diagrams in Quarto markdown files to external SVG images. This improves rendering performance, streamlines content management, and enhances cross-platform consistency.
Introduces interactive "Napkin Math" `callout-notebook` blocks, featuring Python code to generate dynamic visualizations for key system trade-offs and scenarios. Expands the `mlsysim` library with new constants and plotting utilities to support these interactive calculations and comparisons.
Replace the static dev-landing/index.html with the full Quarto-rendered
landing site (book covers, TinyTorch terminal, Hardware Kits, Labs hex
animation, neural-bg). The preview workflow now installs Quarto, renders
landing_site/index.qmd, rewrites mlsysbook.ai URLs to dev-site relative
paths, and deploys the output to the site root.
- Update dev landing to link to /book/ volume chooser instead of old single-volume path
- Add book-index.html as volume picker page deployed at /book/ (Vol I + Vol II cards)
- Fix preview workflow to checkout from dev branch (ref: dev) so landing pages always come from dev
- Add book-index.html to sparse checkout and deploy step
Replace hardcoded Machine-Learning-Systems.pdf/.epub filenames with
find-based discovery in all 4 compress steps (Linux/Windows PDF/EPUB)
and the dev preview deploy workflow. This ensures correct packaging
regardless of the output filename set in Quarto YAML configs.
Set output-file to Machine-Learning-Systems-Vol1 and
Machine-Learning-Systems-Vol2 in all PDF and EPUB configs.
This makes output filenames clean and distinguishable,
serving as single source of truth for downstream packaging.
- Add PYTHONUTF8=1 env var to all Windows Docker run commands (PEP 540)
- Fix generate_figure_list.py to explicitly use encoding='utf-8' in
write_text() instead of relying on system default (cp1252 on Windows)
- The ≈ character (\u2248) in Vol I content triggered charmap codec errors
Add PYTHONIOENCODING=utf-8 env var to all Windows Docker run commands,
and set console/output encoding to UTF-8 in the build script. Fixes
UnicodeEncodeError for characters like ≈ (\u2248) that the default
Windows code page (cp1252) cannot encode.
The preflight script used @"..."@ (expandable here-string) with backtick-escaped
variables, which produced invalid PowerShell when written to a .ps1 file. Switch
to @'...'@ (literal here-string) with normal PowerShell syntax. Format-specific
checks (PDF/EPUB) are appended conditionally using GitHub Actions expressions.
Replace pipe-based PowerShell execution (`$script | docker run ... -Command -`)
with file-based execution (`docker run ... -File script.ps1`) for all Windows
Docker steps: preflight, build, PDF compress, and EPUB compress.
The pipe pattern swallows container stdout and doesn't propagate exit codes,
causing builds to appear successful without actually rendering content.
The Windows container image installs PowerShell 7 at a fixed path
but the short name 'pwsh' is not resolving in docker run commands.
Use the full path 'C:\Program Files\PowerShell\7\pwsh.exe' instead.
Restore Windows container build support that was accidentally removed
in commits a76aab467..a90c8803f. This restores:
- Windows Docker infrastructure (book/docker/windows/)
- Windows container build workflow (infra-container-windows.yml)
- Windows matrix entries in book-build-container.yml
- Windows health check support in infra-health-check.yml
- Windows build flags in book-validate-dev.yml and book-publish-live.yml
Restored from pre-removal state at f85e319d6.
Per request, removed all traces of Windows container builds from the project.
This simplifies the CI pipeline to be Linux-only.
- Deleted `book/docker/windows/` directory and its Dockerfile
- Deleted `.github/workflows/infra-container-windows.yml`
- Removed Windows matrix jobs and steps from `book-build-container.yml`
- Removed Windows inputs and outputs from `book-build-container.yml`
- Removed Windows health checks from `infra-health-check.yml`
- Removed Windows references from `book-publish-live.yml`
- Removed Windows references from `book-validate-dev.yml`
Removed Windows from the `book-validate-dev.yml` workflow. The Windows
container build is no longer supported or required for the dev validation
phase.
- Removed `build_os` input option for Windows
- Disabled Windows health check
- Removed Windows build matrix configuration
- Removed Windows success checks and reporting
The update_contributors script was failing with intermittent 502 Bad Gateway
errors from the GitHub API when fetching commit history. Added retry logic
with exponential backoff (up to 3 retries) to handle transient 502, 503,
and 504 server errors gracefully.
Refactored Windows container build steps to pipe PowerShell scripts via stdin
instead of passing them as command-line arguments to `docker run`. This prevents
PowerShell from incorrectly interpreting curly braces inside the script string
as a ScriptBlock argument.
Applied this fix to:
- Preflight toolchain (Windows)
- Build format (Windows)
- Compress PDF (Windows)
- Compress EPUB (Windows)
Replace subexpression-based OS/architecture logging in dockerized Windows compression steps with format strings to avoid escaping-related parse failures.
Replace embedded subexpression interpolation in the dockerized PowerShell preflight checks with format strings so command source logging does not break script parsing.
Add a pre-pull Windows step that starts the docker service and waits until docker version succeeds so container image pulls do not fail on missing docker_engine pipe.
Make pandoc preflight succeed when only Quarto-bundled pandoc is available, and harden Windows error logging to avoid PowerShell interpolation failures in catch blocks.
Visual audit identified ~85 high-priority figure gaps across Vol 2.
Three categories of work completed:
- Activated ~22 shelved SVGs (renamed from _prefix, wired into QMD)
- Created ~66 new SVGs from scratch following svg-style.md standards
- Replaced ~15 TikZ-in-callout blocks with proper @fig- labeled SVGs
All figures use sandwich prose pattern: intro sentence before the
figure div (telling students what to look for) and takeaway sentence
after (stating the key insight). 47 figures received prose fixes to
ensure complete integration.
SVG standards: viewBox 0 0 680 460, semantic color palette,
Helvetica Neue typography, arrow markers in defs, ≤250-char alt text.
Drop explicit .pdf from output-file in both vol1 and vol2 PDF configs.
Quarto appends the format extension automatically, so including it
produced Machine-Learning-Systems.pdf.pdf.
Remove 14 duplicate .callout-principle blocks from chapter files,
replacing each with prose containing \ref{nte-...} back-references
to the canonical declaration in the part-level principles files.
This mirrors Vol 1's "declare once, reference everywhere" pattern.
Also reclassifies 3 orphan chapter-level observations from
.callout-principle to .callout-perspective, and adds 7 new
cross-references threading principles across chapters.
Adds a utility script to enforce proper Markdown list rendering. This addresses an issue where Quarto/Pandoc might incorrectly parse lists as paragraph continuations if not preceded by a blank line. Applies this formatting fix across all Quarto files by inserting the necessary blank lines.
Add explicit per-check preflight logging and matrix failure instance reporting in the container build workflow, and update stale documentation links and workflow/file path references.
Eliminates the `llms-txt` configuration option from the Quarto website settings. This directive is no longer relevant or required for the site's operation, simplifying the overall configuration.
FP8 is a data format relevant to single-node systems (H100 supports
it natively), so it belongs in Vol 1's precision list rather than as
an orphaned bullet in Vol 2. Network throughput units (Gbps vs GB/s)
remain Vol 2-only under a proper "Additional Units" subsection.
Vol 1 owns its notation (vol1/frontmatter/notation.qmd) as a
standalone document free of distributed systems concepts. Vol 2
(vol2/frontmatter/notation.qmd) uses {{< include >}} to pull in
Vol 1's notation, then adds distributed systems notation on top.
This eliminates duplication while keeping Vol 1 independent of
Vol 2's publication timeline.
- Remove shared/notation.qmd (single shared file)
- Create vol1/frontmatter/notation.qmd (core ML systems notation)
- Create vol2/frontmatter/notation.qmd (extends Vol 1 via include)
- Update all 8 config files to point to volume-specific paths
- Remove contents/shared/ render glob from HTML configs
Replace D_{vol}, R_{peak}, L_{lat} with D_{\text{vol}},
R_{\text{peak}}, L_{\text{lat}} in all QMD files and notation.qmd
to match the canonical notation convention. Also escape bare
FLOPs/$ to FLOPs/\$ in vol1 introduction. 288 replacements
across 24 files.
The "Scaling the Machine: From Node to Fleet" section, including the
TikZ stack-comparison figure and layer walkthrough prose, belongs in
Vol2 where the reader crosses the scaling boundary. Vol1 now flows
directly from Samples/Dollar into ML vs. Traditional Software, with
a two-sentence scope statement in Book Organization. The fn-gpu-parallel
footnote is relocated next to its callsite on line 116.
Use single-quoted python -c code in the Docker RUN command so the command parses correctly under pwsh -Command and avoids parser errors during image build.
Preserve container PATH during Windows docker-run steps and create/verify a python3 alias from Scoop Python so Quarto/Jupyter kernels that invoke python3 work reliably in both install-time and final verification checks.
Install TeX Live under the runner user home instead of /usr/local and resolve tlmgr from that location so direct install-tl succeeds without root write access.
Update Dockerfile and workflow final verification steps to normalize native command exit detection and fail explicitly on non-zero exits, avoiding false positives and false negatives in PowerShell checks.
Avoid checking $LASTEXITCODE after a piped lualatex command by capturing command output first and normalizing exit-code detection, preventing false non-zero failures.
