Rebuild the docs cache when the markdown behind it changes

[simonhamp]

What

Docs pages and navigation were cached for a day with no link back to the markdown files they were rendered from:

return Cache::remember($key.'_'.substr(md5(serialize(config('docs'))), 0, 8), now()->addDay(), $callback);

The key folds in config('docs'), so a Jump version bump invalidates rendered pages — but nothing invalidates them when the markdown itself changes. Deploys ship new docs without clearing the application cache, so an edited page (and the sidebar rendered alongside it) could trail the actual files by up to 24 hours.

Why this shape

Each cache entry now carries a fingerprint of the markdown it was built from, and is rebuilt as soon as that stops matching. The fingerprint is an md5 of every .md file's relative path plus mtime for the platform/version — no file contents are read, so it stays cheap on the hot path while still catching edits, additions and deletions.

Entries written before the fingerprint existed have none, so they miss and rebuild on the first request. No cache flush is needed to deploy this.

local still bypasses the cache entirely, unchanged.

Tests

Four new cases in tests/Feature/Docs/DocsCachingTest.php:

• cached page is reused while the markdown is unchanged (the entry is doctored, then asserted to render — proving the cache is actually hit, not silently recomputed)
• page cached against older markdown is rebuilt
• page cached before fingerprinting existed is rebuilt
• navigation cached before fingerprinting is rebuilt

The stale fixtures are shaped so the view renders rather than throwing — the assertion, not an exception, is what reports a failure.

php artisan test tests/Feature/Docs/DocsCachingTest.php → 7 passed (15 assertions). Pint clean.

🤖 Generated with Claude Code