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:

bash

# 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

bash

# 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:

Converting to lowercase
Removing underscores (_)
Removing hyphens (-)

Examples:

vol1_foundations → vol1foundations
volume_1 → volume1
front-matter → frontmatter

Troubleshooting

Common Issues

Typo in key name:

qmd

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

Missing key in summaries.yml:

yaml

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

Incorrect normalization:

qmd

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

Debugging

Run validation script:

bash

python3 tools/scripts/utilities/validate_part_keys.py

Check specific file:

bash

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