Add `text` language tag to 25 unlabeled fenced code blocks across the
public-facing READMEs. Mostly directory-tree listings, all-contributors
bot instructions, and pseudo-output ASCII blocks — none were getting
syntax highlighting anyway, but the explicit tag silences markdownlint
MD040 and signals intent ("this is plain text, not a forgotten lang").
GitHub's github-markdown-css applies:
.markdown-body table { display: block; width: max-content; max-width: 100%; }
The HTML width="100%" attribute is a presentational hint with lower
specificity than the class selector, so tables with short cell content
were sizing to max-content and not stretching to fill the column.
Tables with long sentences per cell stretched fine, masking the bug.
Add inline style="width:100%" (specificity 1,0,0,0) which overrides
the class-selector rule. Keep width="100%" attribute as a fallback for
non-GitHub renderers (VSCode preview, GitLab, plain HTML viewers).
54 tables updated across 10 READMEs + the two contributor-sync scripts
that regenerate auto-managed tables.
The sub-project READMEs used an old-school nested-table card design
with hardcoded bgcolor="#ffffff", "#cfd6dd", "#eef2f7" plus deprecated
HTML4 attributes (cellpadding, cellspacing, border). It looked good in
light mode but produced harsh white islands in GitHub's dark theme,
which is what most readers see today.
Across 11 sub-READMEs:
- Strip the card wrapper so data tables are just clean
<table width="100%"> with semantic <thead>/<tbody>. Headers keep
their column widths; bgcolor/valign/zebra-stripe cruft is removed
(GitHub provides its own theme-aware striping).
- Convert the early-release callouts (and mlperf-edu's two-tier
status block + "source of truth" note + interviews' two info boxes)
to GitHub-native > [!NOTE] / > [!WARNING] / > [!TIP] callouts.
These are theme-aware, get proper icons, and render correctly in
light AND dark mode.
Net result: 528 lines of HTML cruft removed, 230 lines of clean
markdown added. Visual identity is preserved (callouts still stand
out, tables still stretch full-width) while becoming dark-mode safe
and consistent with the main README.
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.
- Add wrap_readme_data_tables.py to frame <table>+<thead>/<tbody> blocks in a
98% width panel (#cfd6dd border, #eef2f7 headers, zebra body rows where
applied manually in converted tables).
- Apply wraps to book, kits, labs, slides, tinytorch; tbody wraps for kits
docs/related and instructors overview.
- Convert remaining Markdown tables in mlsysim, mlperf-edu, and interviews to
the same HTML pattern; replace StaffML markdown callouts with HTML panels.
- Add thead rows to kits/instructors body-only tables for clearer hierarchy.
Replace markdown blockquotes with a shared centered table pattern
(cellpadding, bgcolor panel, h3 + aligned paragraphs) so GitHub renders
consistent spacing. Align labs and mlsysim DEV-BANNER with the same layout
and 2026 messaging.
Use a short top-of-README callout for periodic-table, StaffML, TinyTorch,
slides, and instructors: live with the 2026 release, expect steady iteration,
link to GitHub issues. Slides banner replaces dev-only wording with the same
framing while keeping dev/live badges.
Audit of the eight sub-project READMEs showed inconsistent surrounding
text around the auto-managed contributor table — some had a Legend line,
some didn't; instructors used a different heading style; interviews was
missing the thanks blurb and CTA; mlsysim was missing the END marker
and the recognition CTA.
Standardize all eight to the same template: heading + thanks blurb +
legend + ALL-CONTRIBUTORS markers + Recognize-a-contributor CTA.
Per-project quirks preserved: interviews keeps its closing author
sign-off paragraph; CTA wording stays project-specific (e.g. labs
suggests "code, tutorial, test, or doc" while kits suggests
"tool, test, video, or doc").
Per-project sections kept (not consolidated into root). Sub-READMEs
are landing pages, sub-projects could be extracted to standalone repos
later, and recognition is more meaningful where the work lives. The
root README continues to aggregate everything via the existing
sectioned tables.
Closes the gap where Slides and Instructor Site were first-class Quarto
sites but invisible to the contributor recognition pipeline, and fixes
two pre-existing holes for mlsysim/interviews.
Workflows
- all-contributors-add.yml: add `slides` and `instructors` to PROJECTS;
add `slide`/`instructor` aliases. Tighten the LLM prompt with explicit
multi-type and emoji/punctuation rules, and add a deterministic regex
fallback that scans the trigger comment for type keywords and unions
them with the LLM result so a flaky classification never drops a tag.
- update-contributors.yml: add `mlsysim`, `interviews`, `slides`,
`instructors` to the push trigger paths and to the file/commit lists,
so edits to those configs actually rebuild and push READMEs.
Generators
- generate_main_readme.py: refactor the per-section block to a single
PROJECT_SECTIONS table so adding a project is one line; add Slides
and Instructor Site sections.
- generate_readme_tables.py: register `slides` and `instructors`.
Configs / READMEs
- New `slides/.all-contributorsrc` and `instructors/.all-contributorsrc`
seeded with profvjreddi.
- Add ALL-CONTRIBUTORS-LIST markers + recognize-a-contributor blurb to
`slides/README.md` and `instructors/README.md`.
- Regenerate root, slides, instructors, and (sorted-badge drift) the
interviews README via the generators.
Docs
- Refresh `.github/workflows/contributors/README.md` to list all 8
projects and document the canonical-list-in-PROJECTS contract.
Post-migration the corpus holds 9,199 published questions (the paper's
number; site pre-migration reported 8,053 due to the v1 filter-predicate
bug). Rounded display count bumped everywhere in the top-level
interviews/README.md to reflect the accurate current state.
Restructure sample questions using collapsible <details> with bold
summary lines and <blockquote> for question text. Each track now has
a clean visual hierarchy: track heading → collapsible questions →
indented answers with napkin math.
- Move StaffML app from /interviews/ to /staffml/ (basePath, destination_dir)
- Add /interviews/ → /staffml/ redirect for old URL support
- Add staffml to site deploy skip list
- Upgrade interviews/README.md with star funnel hero + Launch StaffML CTA
- Promote v3 rich-card landing page to default index.qmd
- Archive original landing as index-v1.qmd
- Fix navbar wrapping: icon-only below 1400px, no-wrap on right-side items
- Update star CTA copy: "helps others discover" (inclusive wording)
- 15 hand-picked questions across all tracks and Bloom levels
- Each with model answer + napkin math in collapsible details
- Depth chains section with example L1→L6+ memory chain
- Vault stats table (5,700+ Qs, 1,000+ chains, 650+ concepts)
- CTA linking to the full app
- Rewrote README to reflect current structure (no more cloud/, edge/ dirs)
- Removed 10 broken links to non-existent files
- Updated title to "StaffML: ML Systems Interview Playbook"
- Added development instructions and CI/CD reference
- Curriculum map SVG: slate color for StaffML box (#475569)
- Smoke tests in both dev and live workflows: corpus integrity, required
fields, valid levels, taxonomy size, manifest consistency, static assets
- Build fails if critical pages missing or data is malformed
- README: StaffML build badge, updated question count and platform status
Restructure all 4 tracks from arbitrary round-based files to
learner-journey-based scopes. Each file represents the system
the student is reasoning about, with competency sub-sections
and L3→L6+ mastery levels inside.
Cloud: Single Machine → Distributed Systems → Serving Stack → Production Ops
Edge: Hardware Platform → Real-Time Pipeline → Deployed System
Mobile: Device & SoC → App Experience → Ship & Update
TinyML: Microcontroller → Sensing Pipeline → Deployed Device
Old round files preserved in _legacy/ folders. All cross-references
updated in README, STUDY_GUIDE, TOPIC_MAP, _quarto.yml, and index.qmd.
Fix several mathematical calculations in the system design interview flashcards:
- Correct pipeline bubble fraction formula to (P-1)/(M+P-1)
- Fix Erlang M/M/1 queuing length calculation (L vs Lq)
- Fix speculative decoding pass count calculation
- Correct TinyML BLE gateway bandwidth math (5 gateways, not 1)
- Correct mobile monitoring storage math (1 byte vs 0.1 KB)
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.
Add "Why One Repository" section with authorial voice explaining the
integrated curriculum design. Replace flat component list with tiered
curriculum diagram (SVG) showing how textbook, labs, TinyTorch,
MLSys·im, hardware kits, and interview playbook connect. Split tables
into "For Students" and "For Educators" sections. Fix links so live
components point to mlsysbook.ai and in-development components point
to repo READMEs. Add dev banners to component READMEs (kits, mlsysim,
labs, interviews, slides). Update branch guide to clarify what is live
at mlsysbook.ai vs under development on dev.
Rebrand from "Interview Hub" to "The ML Systems Interview Playbook"
and restructure for depth, navigation, and educational value.
- Add "Numbers Every ML Systems Engineer Should Know" reference table
grounded in the textbook's constants.py (invariants, scaling rules,
hardware snapshot)
- Enhance all 36 flashcard questions with Common Mistake, Napkin Math,
and Key Equation fields where applicable
- Expand Round 5 (Visual Architecture Debugging) from 2 to 7 Mermaid
diagram challenges
- Strengthen Architect's Rubric from 3 to 6 evaluation axes with
scoring guide
- Add topic sections within each round, sorted by difficulty
- Add inline topic tags and cross-cutting Topic Index in README
- Delete duplicate 06_System_Design_Rubric.md
- Feature playbook in root README (top nav, Learning Stack, Start Here)
- Delete old textbook-based buckets.
- Introduce 4 industry-aligned 'Rounds': Single-Node Physics, Distributed Infrastructure, Production Serving, and Operations/Economics.
- Migrate and adapt seeded questions into the new Round format.
- Update Hub README to emphasize 'Systems-First' hiring philosophy.
- Implement Level 1 (Screen), Level 2 (Architect), and Level 3 (Lead) taxonomy.
- Extract all seed questions directly from Volume I and Volume II chapter math/callouts.
- Remove generic 'AI slop' questions and replace with high-signal 'Silicon Realist' physics.
- Update Hub README to explain the Funnel of Mastery.
- Remove marketing branding, 'Deep Dive' links, and 'Walls' cheatsheet.
- Simplify Interview Hub into professional question/answer categories.
- Ensure all content is technical and free of AI-generated commentary.
- Add 'Work in Progress' note to interviews/README.md.
- Standardize lab terminology (Act -> Part) in orientation lab.
- Enhance scaling law constants with SystemAssumption metadata in mlsysim.
- Implement 'The Blueprint' Interview Guide and Flashcard Hub.
- Add 'AI Systems Arena' for LeetCode-style design challenges.
- Integrate 'mlsysim audit' CLI for local hardware profiling.
- Setup GitHub Actions for automated contributor recognition and welcome messages.
- Add dynamic 'Trending Questions' leaderboard based on community upvotes.
- Update root README and main landing page for practitioner focus.
