cs249r_book/book/docs/PART_KEY_VALIDATION.md

Part Key Validation System

Overview

The part key validation system ensures that all \part{key:xxx} commands in your .qmd files reference valid keys defined in quarto/contents/parts/summaries.yml. This prevents build failures and ensures consistent part titles throughout your book.

How It Works

1. Pre-Scan Validation (Lua Filter)

The quarto/filters/inject_parts.lua filter includes a pre-scan step that:

• Scans the entire document before processing any blocks
• Validates all keys against summaries.yml
• Reports issues immediately with detailed error messages
• Stops the build if any invalid keys are found

2. Standalone Validation Script

The tools/scripts/utilities/validate_part_keys.py script provides:

• Independent validation without running the full build
• Comprehensive reporting of all issues
• File and line number information for each problem
• Available keys listing for reference

Usage

Pre-commit Hook (Recommended)

The validation runs automatically on every commit:

# Pre-commit will run validation automatically
git add .
git commit -m "Your commit message"
# If there are invalid keys, the commit will be blocked

Manual Validation

# Run the validation script from the book directory
python3 tools/scripts/utilities/validate_part_keys.py

# Or use the wrapper script
./tools/scripts/check_keys.sh

Available Keys

The following keys are defined in quarto/contents/parts/summaries.yml:

Key	Title	Type
frontmatter	Frontmatter	Division
volume_1	Volume I: Introduction to Machine Learning Systems	Division
vol1_foundations	ML Foundations	Part
vol1_development	System Development	Part
vol1_optimization	Model Optimization	Part
vol1_operations	System Operations	Part
volume_2	Volume II: Machine Learning Systems at Scale	Division
vol2_scale	Foundations of Scale	Part
vol2_distributed	Distributed Systems	Part
vol2_production	Production Challenges	Part
vol2_responsible	Responsible Deployment	Part
backmatter	References	Division
references	Bibliography	Lab

Error Handling

Lua Filter Errors

When the Lua filter encounters an invalid key:

❌ CRITICAL ERROR: UNDEFINED KEY 'invalid_key' not found in summaries.yml
📍 Location: RawBlock processing
🔍 DEBUG: Key 'invalid_key' found in RawBlock
📍 RawBlock content: \part{key:invalid_key}
📍 RawBlock format: latex
🔍 Available keys: frontmatter, volume_1, vol1_foundations, vol1_development, vol1_optimization, vol1_operations, volume_2, vol2_scale, vol2_distributed, vol2_production, vol2_responsible, backmatter, references
💡 Check your .qmd files for \part{key:invalid_key} commands
🛑 Build stopped to prevent incorrect part titles.

Python Script Errors

When the validation script finds issues:

❌ ISSUES FOUND:
   📄 quarto/contents/vol1/introduction/introduction.qmd:15
      - Key: 'invalid_key' (normalized: 'invalidkey')
      - Status: NOT FOUND in summaries.yml

💡 To fix these issues:
   1. Add the missing keys to quarto/contents/parts/summaries.yml
   2. Or correct the key names in the .qmd files
   3. Or remove the \part{key:xxx} commands if not needed

Key Normalization

Keys are normalized for comparison by:

1. Converting to lowercase
2. Removing underscores (_)
3. Removing hyphens (-)

Examples:

• vol1_foundations → vol1foundations
• volume_1 → volume1
• front-matter → frontmatter

Troubleshooting

Common Issues

1. Typo in key name:

   \part{key:vol1_foundations}  # ✅ Correct
   \part{key:vol1_foundationss}  # ❌ Typo
   

2. Missing key in summaries.yml:

   # Add to quarto/contents/parts/summaries.yml
   - key: "new_section"
     title: "New Section"
     description: "Description here"
   

3. Incorrect normalization:

   \part{key:vol1_foundations}  # ✅ Will match 'vol1foundations'
   \part{key:vol1-foundations}  # ✅ Will match 'vol1foundations'
   

Debugging

1. Run validation script:

   python3 tools/scripts/utilities/validate_part_keys.py
   

2. Check specific file:

   grep -n "\\part{key:" quarto/contents/**/*.qmd
   

---

Last updated: January 2026 Validation script: tools/scripts/utilities/validate_part_keys.py Lua filter: quarto/filters/inject_parts.lua