2026-04-01 | 🔍 The Audit That Barely Looked 👀
🐛 The Problem
🔗 A post-deploy broken link audit was sampling 30 pages from the live site but only checking a single link across all of them.
📊 The output told the story clearly: 30 pages sampled, 1 link checked, 0 broken links found. That is a suspiciously clean bill of health.
🕵️ Root Cause
🧩 The link extraction function only recognized two forms of internal links: absolute paths starting with a forward slash, and full URLs starting with the site domain.
🌐 But Quartz, the static site generator powering the site, generates all its content links as dot-relative paths. Links like dot-slash reflections slash 2026-03-30 or dot-dot-slash chickie-loo slash entry are the norm.
🚫 The extractor simply skipped every one of these relative links, treating them as external or invalid. Only a single RSS feed link in the page metadata happened to use a full URL, and that was the one lonely link that got counted.
🔧 The Fix
🛠️ The solution replaces manual prefix matching with the standard URL constructor, which handles all forms of relative URL resolution correctly.
🆕 The function now accepts the source page URL as a third parameter. Every href gets resolved against that page URL using the built-in URL API, which correctly handles dot-slash for siblings, dot-dot-slash for parent navigation, root-relative paths, and full absolute URLs.
📐 After resolution, the function strips anchors and query parameters, normalizes trailing slashes, and filters to same-domain links only.
✅ This approach is both simpler and more correct than the original manual path handling.
🧪 Testing
🔬 The test suite grew from 18 to 22 tests. New cases verify dot-relative links from the home page, parent-relative links from subpages, sibling resolution from nested pages, and graceful handling of javascript and mailto schemes.
📋 All 22 tests pass.
🎯 Key Takeaway
🏗️ When your static site generator changes its link format, your auditing tools need to keep up. Hardcoded prefix checks are brittle. Standard URL resolution is robust.
🔄 The URL constructor is one of those built-in tools that does the right thing for an enormous range of inputs. Reaching for it first would have prevented this bug entirely.
📚 Book Recommendations
📖 Similar
- Release It! by Michael T. Nygard is relevant because it covers designing systems that monitor themselves effectively, including the kind of post-deploy verification this audit performs.
- A Philosophy of Software Design by John Ousterhout is relevant because it emphasizes choosing the right abstraction level, exactly the lesson of using URL resolution instead of manual string matching.
↔️ Contrasting
- The Art of Unit Testing by Roy Osherove offers guidance on when and how to test, providing a counterpoint to the approach of testing only pure functions while the integration-level bug slips through.
🔗 Related
- Web Operations by John Allspaw and Jesse Robbins explores the operational side of web deployments and the importance of verification steps like link auditing after every deploy.