fix(ci): prevent gh-pages branch bloat

[blackgirlbytes]

Problem

The gh-pages branch grew to 9.6 GB causing GitHub Pages deployments to fail with:

System.IO.IOException: No space left on device

Root Cause

The deploy workflow had keep_files: true which preserved all existing files across deployments:

- name: Deploy to /gh-pages
  uses: peaceiris/actions-gh-pages@v3
  with:
    keep_files: true  # <-- THE PROBLEM

This caused bloat because:

1. Docusaurus hashes asset filenames (e.g., image-abc123.png)
2. When an image is updated/renamed, a new hashed file is created
3. The old file is never deleted due to keep_files: true
4. Over months of deployments, thousands of orphaned files accumulate

Example:

Deploy #1: image-aaa.png (500KB)
Deploy #2: image-bbb.png (500KB) + image-aaa.png still there
Deploy #3: image-ccc.png (500KB) + image-bbb.png + image-aaa.png
... repeat 100x ...

Solution

1. Set keep_files: false - Do clean deployments instead of accumulating files
2. Set force_orphan: true - Prevent git history bloat by creating fresh commits
3. Preserve pr-preview/ directory - Copy it from the current gh-pages before deploying so active PR previews aren't deleted

Each deployment now produces a clean gh-pages branch with only:

• The current documentation build (~500 MB)
• Active PR preview directories

Testing

• Manually cleaned gh-pages branch (9.6 GB → 515 MB)
• Verified site deploys correctly after cleanup
• Verify PR previews are preserved after this change merges

Related

This PR was created after manually cleaning the gh-pages branch to fix the immediate deployment failure.

[Copilot]

Pull request overview

This PR fixes GitHub Pages deployment failures caused by the gh-pages branch growing to 9.6 GB. The solution changes from incremental deployments to clean deployments while preserving active PR previews.

Key changes:

• Switches from keep_files: true to keep_files: false to prevent accumulation of orphaned hashed assets
• Adds force_orphan: true to prevent git history bloat
• Manually preserves the pr-preview/ directory by copying it from the current gh-pages branch before deployment

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.

[jamadeo]

Nice! Looks like a clean solution to reducing the bloat of old pr preview deployments.