Formalize book.js patch management system

[subhobhai943]

Overview

This PR implements a comprehensive patch management system for theme/book.js customizations, addressing issue #2924. Instead of directly editing book.js, we now maintain customizations as patches that can be applied to any mdbook version.

🎯 Problem Solved

Before: Direct edits to book.js made mdbook updates risky and customizations hard to track
After: Formalized patch system with modular enhancements, CI verification, and automated tools

🛠️ Implementation

1. Patch Management System

• theme/patches/original/book.js - Vanilla mdbook v0.4.40 book.js
• theme/patches/*.patch - Individual patches for each customization
• theme/scripts/ - Management scripts for applying, verifying, and extracting patches

2. Modular Enhancements

• theme/comprehensive-rust-enhancements.js - Contains most custom logic
• Minimal patches to book.js (just integration points)
• Graceful fallbacks if enhancement file fails to load

3. Automation & CI

• GitHub Action verifies patch integrity on every PR
• Makefile provides convenient commands
• Scripts handle mdbook version updates automatically

📝 Files Added/Modified

New Files

theme/
├── comprehensive-rust-enhancements.js     # Modular enhancements
├── patches/
│   ├── original/book.js                  # Original mdbook file
│   ├── 001-enhanced-playground.patch      # Playground enhancements
│   └── 002-theme-improvements.patch       # Theme improvements
├── scripts/
│   ├── apply-patches.sh                 # Apply all patches
│   ├── extract-patches.sh               # Extract current patches
│   ├── verify-patches.sh                # Verify patch integrity
│   └── update-mdbook-version.sh         # Update mdbook version
├── Makefile                           # Convenient commands
└── README-patching.md                 # Complete documentation

.github/workflows/
└── verify-book-js-patches.yml         # CI verification

Modified Files

• book.toml - Added comprehensive-rust-enhancements.js to additional-js

🎆 Features & Improvements

Customizations Preserved

• ✅ Unused lint suppression - #![allow(unused)] unless warnunused class
• ✅ Analytics tracking - Google Analytics for playground usage
• ✅ Enhanced error handling - Better error messages and stderr support
• ✅ Extended timeouts - 15s timeout for playground requests
• ✅ Rust 2024 edition - Support for latest Rust edition
• ✅ Theme validation - Better theme ID validation

New Capabilities

• ✅ Automatic patch application - make apply-patches
• ✅ Patch verification - make verify-patches
• ✅ Easy mdbook updates - make update-mdbook VERSION=v0.4.41
• ✅ CI integration - Automated patch integrity checks
• ✅ Clear documentation - Complete usage guide

🧪 Testing

Manual Testing

# Test patch application
cd theme
make apply-patches
make verify-patches

# Test syntax
make test-syntax

# Test book building
mdbook serve

CI Testing

• ✅ Patches apply cleanly
• ✅ Generated file matches expected
• ✅ JavaScript syntax validation
• ✅ All required files exist

📋 Usage Examples

For Daily Development

# Normal development - no changes needed
mdbook serve

Adding New Customizations

# 1. Add to modular file (preferred)
vim theme/comprehensive-rust-enhancements.js

# 2. Or edit book.js directly, then extract patches
vim theme/book.js
make extract-patches

Updating mdbook Version

make update-mdbook VERSION=v0.4.41

🔗 Addresses Issue Requirements

✅ Store modifications as patches - Done via theme/patches/*.patch
✅ CI verification - Implemented in .github/workflows/verify-book-js-patches.yml
✅ Update script - theme/scripts/update-mdbook-version.sh
✅ Minimize patches - Modular design reduces patch size
✅ Future-compatible - System works with any mdbook version

🤝 Collaboration Notes

Following @djmitche's suggestion to minimize patches through modularization and @mgeisler's vision for a robust patch system. This implementation:

• Keeps patches small and focused
• Provides comprehensive tooling
• Includes thorough documentation
• Ensures backward compatibility
• Makes mdbook updates safe and easy

📚 Documentation

Complete documentation is available in theme/README-patching.md including:

• System overview and architecture
• Step-by-step usage instructions
• Troubleshooting guide
• Update procedures
• Development workflows

Fixes #2924

---

Testing Checklist:

• Patches apply cleanly
• Generated book.js matches current functionality
• JavaScript syntax is valid
• CI workflow passes
• Documentation is complete
• Scripts are executable and functional

[google-cla]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

[gribozavr]

@subhobhai943 Thank you for your contribution! Before we proceed with the code review, please sign the CLA following the instructions from the CLA bot above my comment.

[mgeisler]

The scripts should just be stored as executable directly in the repository. The workflow should not have to fix this, we can fix it once and for all 😄

[mgeisler]

I'm pretty sure this is part of a base install on the GitHub runners?

[mgeisler]

We don't really output emojis in any of our other scripts. Please try to follow the existing style and remove it from here.

[subhobhai943]

Thanks for the review, @mgeisler!

• Removed the chmod +x theme/scripts/*.sh step; scripts are now stored as executable in the repo as suggested.
• Dropped the apt-get install patch step; relying on the runner’s base tools.
• Updated log messages to follow repository style (no emojis).

The updated workflow keeps the verification steps intact and uses the scripts directly. Please let me know if you’d like any additional adjustments.