Cache Control Anti-Pattern: Why Aggressive Cache-Busting is Bad for Documentation Sites

Important Notice

This guide documents how to implement aggressive cache-busting headers in doc-builder, but we strongly recommend against using this approach. This documentation exists for educational purposes and to explain why this is considered an anti-pattern for static documentation sites.

Why Cache-Busting is a Bad Idea for Documentation

1. Performance Degradation

Increased Load Times: Every page visit requires a full server round-trip
No Offline Access: Users can't view previously visited pages without internet
Bandwidth Waste: Repeatedly downloading unchanged content
Server Load: Unnecessary strain on your hosting infrastructure

2. Poor User Experience

Documentation is typically static content that changes infrequently
Users expect fast page loads when navigating documentation
Browser back/forward navigation becomes sluggish
Search engines may penalize sites with poor performance

3. Cost Implications

Higher bandwidth costs on platforms like Vercel
Increased CDN usage without benefits
More compute resources needed to serve requests

4. Against Web Best Practices

Static documentation should leverage browser caching
CDNs exist specifically to cache and serve static content efficiently
Modern web performance relies on intelligent caching strategies

How to Implement No-Cache Headers (Not Recommended)

Despite the downsides, here's how you would implement aggressive cache-busting if absolutely necessary:

Option 1: HTML Meta Tags

Add these meta tags to the HTML template in lib/core-builder.js:

// In the generateHTML function, add to the <head> section:
<meta http-equiv="Cache-Control" content="no-cache, no-store, must-revalidate">
<meta http-equiv="Pragma" content="no-cache">
<meta http-equiv="Expires" content="0">

Option 2: Vercel Configuration

Create or modify vercel.json in your output directory:

{
  "headers": [
    {
      "source": "/(.*)",
      "headers": [
        {
          "key": "Cache-Control",
          "value": "no-cache, no-store, must-revalidate"
        },
        {
          "key": "Pragma",
          "value": "no-cache"
        },
        {
          "key": "Expires",
          "value": "0"
        }
      ]
    }
  ]
}

Option 3: Modified Core Builder

To add cache-busting query parameters to all internal links:

// In core-builder.js, modify link generation:
function addCacheBuster(url) {
  const timestamp = Date.now();
  const separator = url.includes('?') ? '&' : '?';
  return `${url}${separator}v=${timestamp}`;
}

Better Alternatives (Recommended)

1. Intelligent Cache Headers

Instead of no-cache, use smart caching:

{
  "headers": [
    {
      "source": "/(.*).html",
      "headers": [{
        "key": "Cache-Control",
        "value": "public, max-age=3600, stale-while-revalidate=86400"
      }]
    },
    {
      "source": "/css/(.*)",
      "headers": [{
        "key": "Cache-Control",
        "value": "public, max-age=31536000, immutable"
      }]
    }
  ]
}

2. Version-Based Cache Busting

Only bust cache when content actually changes:

// In doc-builder.config.js
module.exports = {
  // ... other config
  buildVersion: require('./package.json').version,
  // Assets will be served as: style.css?v=1.4.3
};

3. Content-Based Hashing

Use build tools to generate hashed filenames:

style.css → style.a8f7c2.css
Cache forever with new filename on changes

4. Service Worker Strategy

Implement a service worker for intelligent caching:

Cache static assets aggressively
Network-first for HTML content
Offline fallback for better UX

The Real Solution to Browser Title Issues

The "Quarterly Sales Report" issue mentioned is likely due to:

Browser Session Restore: Browser remembering old tab titles
History Cache: Browser's back/forward cache
Tab Suspension: Browser saving memory by caching tab state

Simple Fixes:

Hard refresh: Ctrl+Shift+R (Windows/Linux) or Cmd+Shift+R (Mac)
Clear browser cache for the specific site
Open the page in an incognito/private window

Conclusion

Aggressive cache-busting is an anti-pattern for documentation sites. The performance and user experience costs far outweigh any benefits. Instead:

Use intelligent caching strategies
Implement version-based cache busting for assets
Trust browsers to handle HTML caching appropriately
Don't disable caching entirely

Remember: Documentation sites are meant to be fast, reliable, and accessible. Proper caching is essential to achieving these goals.