Donkey on the Edge — Refactor Plan (May 2026)

Donkey on the Edge — Refactor Plan (May 2026)

Companion to CLAUDE.md. Human-readable plan; refactor-log-May2026.md records what has actually been done.

Objectives (from CLAUDE.md)

  1. Preserve all content. No action may make any page or post unavailable (~1,788 posts, 1968→2026; ~1,854 built pages).
  2. Shrink the repo (currently >2G). Split actively-used site from legacy content/assets; move legacy to backup disk, off GitHub.
  3. Look & feel unchanged as templates/CSS are modernised.
  4. Fix rendering bugs — mobile alignment, viewport overflow, broken pagination, design breakage.
  5. Repair broken image links caused by the Movable Type → later-CMS moves (MT assets_c/ paths etc.).

Diagnosis (measured)

Item Size / count Tracked? Note
.git history 866M — Bloated by large binaries in history
_site/ 814M No (ignored) Local build output — safe to delete
images/ 760M Yes Real payload; ~16 huge files dominate
_posts/ ~7.3M / 1,788 md Yes The crown jewels; tiny in bytes
staticman_* remote branches 295 remote Orphaned dead-comment-system branches

Largest history blobs: images/jed/anniversaryparty.mov (60M), secret-mosquito-for-Jed.mov (56M), int-2011.zip (47M), 3× isolationoffice*.jpeg (~30M), portfolio.pdf (15M), HMRC photos (~10M).

Broken image links by class:

  • Class 1 — assets_c/YYYY/MM/... (MT thumbnails): 54 posts. No assets_c/ dir exists; all 404. Originals likely under images/. Heuristic.
  • Class 2 — absolute hostname URLs: 226 posts (~137 http://www.donkeyontheedge.com/images/...). Mechanical rewrite to root-relative /images/....
  • Class 3 — .shtml links: 19 posts. SSI-era, likely dead. Minor.
  • Out of scope: external Flickr/PayPal images.

Build: classic GitHub Pages (github-pages gem, no Actions). images/ is the store — there is no i/ directory.

Key sequencing rule

Link repair must precede asset archival / history purge. Fixing Class-1 links means locating the original each broken link should point to. Archiving or purging images first risks deleting a file a broken link still needs — silently, since the link was already broken. Order: baseline → repair → verify → shrink.

The build-and-diff baseline harness is the keystone: it is simultaneously the image-link audit and the safety net that proves “look & feel unchanged” for the CSS/template work.

Phases

  • Phase 0 — Zero-risk hygiene. Delete local _site; clean .gitignore; untrack committed .DS_Store. No content/history change.
  • Phase 1 — Baseline harness. Reproducible jekyll build; inventory every output page and every image URL; flag which resolve to an existing file. This is the audit + safety net.
  • Phase 2 — Backup safety net. git clone --mirror + working-tree archive to backup disk before anything irreversible.
  • Phase 3 — Class-2 link repair. Absolute → root-relative. Mechanical, high-volume, baseline-diffed.
  • Phase 4 — Class-1 assets_c repair. Heuristic original-mapping, reviewed. Class-3 .shtml cleanup alongside.
  • Phase 5 — Asset diet. Archive zero-reference legacy + oversized media off to backup disk; downscale still-displayed large images. Keep referenced microsites (facebook/, h5/, ala.html, berg.com/, britishmuseum/, mahir/) until individually verified.
  • Phase 6 — History rewrite (irreversible; needs Phase 2 + explicit sign-off). git filter-repo to purge large binaries; delete 295 staticman_* branches; force-push.
  • Phase 7 — Rendering/CSS modernisation. Audit 218K main.css, strip unused framework CSS, fix mobile/viewport/pagination bugs — each change verified against the Phase 1 baseline.

Conventions

  • Commits are made by the user via GitHub Desktop, not by Claude.
  • Every executed action is appended to refactor-log-May2026.md.
  • Nothing irreversible happens before Phase 2 backup + explicit sign-off.