HTML Recovery Tool: Restore lecture sites from GitHub Release assets

[mmcky]

Summary

Lecture repos (e.g. lecture-python.myst) already attach built HTML as release assets via softprops/action-gh-release@v2 (and the new publish-gh-pages action supports create-release-assets: 'true').

What's missing is a recovery tool that can:

1. Download the latest HTML release asset for a given lecture repo
2. Extract and serve/deploy the HTML (e.g. to GitHub Pages, Netlify, or a local server)
3. Optionally restore multiple lecture sites at once from their release assets

Motivation

• Git repos are inherently distributed — anyone with a clone has full history
• Built HTML is ephemeral and hard to reproduce — requires specific build toolchain (Jupyter Book, conda environment, GPU for some lectures)
• If a lecture site goes down, the fastest recovery path is deploying pre-built HTML, not rebuilding from source
• Release assets are already being created — we just need a tool to consume them for recovery

Proposed Scope

CLI / Reusable Workflow

A simple tool (script or GitHub Action) that:

# Recover a single site
python recover.py --repo QuantEcon/lecture-python.myst --output ./site

# Recover all lecture sites
python recover.py --org QuantEcon --pattern 'lecture-*' --output ./sites

# Deploy recovered site to GitHub Pages
python recover.py --repo QuantEcon/lecture-python.myst --deploy gh-pages

Key Features

• Download latest release asset (HTML tar.gz) from any lecture repo
• Verify integrity via SHA256 checksum (already created by publish-gh-pages)
• Extract and optionally serve locally for verification
• Deploy to GitHub Pages or alternative hosting
• Batch recovery across multiple repos
• List available recovery points (releases) for a repo

Context

This issue originated from a review of QuantEcon's backup strategy in workflow-backups. The conclusion was that HTML recovery is the highest-priority backup concern — git repos are self-backing, but built artifacts are not.

Related

• publish-gh-pages create-release-assets feature
• Current publish.yml in lecture repos using softprops/action-gh-release@v2
• workflow-backups repo (S3-based git mirror backups)