[Cache] Migrate historical changelog entries and add new ones (#27469)

* [Cache] Migrate historical changelog entries and add new ones

Migrates 6 inline changelog entries from src/content/docs/cache/changelog.mdx
to separate .mdx files and adds 3 new changelog entries, following the

Migrated entries (2024-07 to 2025-01):
- Regionalized generic tiered cache (2024-07-19)
- Cache rules templates (2024-09-05)
- Cache versioning (2024-11-07)
- Shard cache by cache key (2024-11-07)
- Smart Tiered Cache for R2 (2024-11-20)

New entries (2025-02 to 2025-08):
- Configurable multiplexing HTTP/2 to origin (2025-02-12)
- Workers Fetch API override cache rules (2025-04-04)

Cleans up changelog.mdx by removing 36 lines of legacy inline content.

* Apply suggestions from code review

---------

Co-authored-by: angelampcosta <92738954+angelampcosta@users.noreply.github.com>

src/content/changelog/cache/2024-07-19-regionalized-generic-tiered-cache.mdx

@@ -0,0 +1,29 @@
+---
+title: Regionalized Generic Tiered Cache for higher hit ratios
+description: Generic Global Tiered Cache now hashes content within a region's data centers to reduce duplication and increase cache efficiency.
+products:
+  - cache
+date: 2024-07-19
+---
+
+You can now achieve higher cache hit ratios with [Generic Global Tiered Cache](/cache/how-to/tiered-cache/#generic-global-tiered-cache). Regional content hashing routes content consistently to the same upper-tier data centers, eliminating redundant caching and reducing origin load.
+
+## How it works
+
+Regional content hashing groups data centers by region and uses consistent hashing to route content to designated upper-tier caches:
+
+- Same content always routes to the same upper-tier data center within a region.
+- Eliminates redundant copies across multiple upper-tier caches.
+- Increases the likelihood of cache HITs for the same content.
+
+## Example
+
+A popular image requested from multiple edge locations in a region:
+
+- **Before**: Cached at 3-4 different upper-tier data centers
+- **After**: Cached at 1 designated upper-tier data center
+- **Result**: 3-4x fewer cache MISSes, reducing origin load and improving performance
+
+## Get started
+
+To get started, enable [Generic Global Tiered Cache](/cache/how-to/tiered-cache/#generic-global-tiered-cache) on your zone.

src/content/changelog/cache/2024-09-05-cache-rules-templates.mdx

@@ -0,0 +1,30 @@
+---
+title: One-click Cache Rules templates now available
+description: Pre-built templates in the Cloudflare dashboard make it easy to create optimized cache rules instantly.
+products:
+  - cache
+date: 2024-09-05
+---
+
+You can now create optimized cache rules instantly with **one-click templates**, eliminating the complexity of manual rule configuration.
+
+## How it works
+
+1. Navigate to **Rules** > **Templates** in your Cloudflare dashboard.
+2. Select a template for your use case.
+3. Click to apply the template with sensible defaults.
+4. Customize as needed for your specific requirements.
+
+## Available cache templates
+
+- **Cache everything**: Adjust the cache level for all requests.
+- **Bypass cache for everything**: Bypass cache for all requests.
+- **Cache default file extensions**: Replicate Page Rules caching behavior by making only default extensions eligible for cache.
+- **Bypass cache on cookie**: Bypass cache for requests containing specific cookies.
+- **Set edge cache time**: Cache responses with status code between 200 and 599 on the Cloudflare edge.
+- **Set browser cache time**: Adjust how long a browser should cache a resource.
+
+## Get started
+
+To get started, go to [**Rules > Templates**](https://dash.cloudflare.com/?to=/:account/:zone/caching/cache-rules) in the dashboard. For more information, refer to the [Cache Rules documentation](/cache/how-to/cache-rules/).
+

src/content/changelog/cache/2024-11-07-cache-versioning.mdx

@@ -0,0 +1,37 @@
+---
+title: Stage and test cache configurations safely
+description: Cache now supports versioned environments for staging configurations and purging staged content independently.
+products:
+  - cache
+date: 2024-11-07
+---
+
+You can now stage and test cache configurations before deploying them to production. Versioned environments let you safely validate cache rules, purge operations, and configuration changes without affecting live traffic.
+
+## How it works
+
+With versioned environments, you can:
+
+1. **Create staging versions** of your cache configuration.
+2. **Test cache rules** in a non-production environment.
+3. **Purge staged content** independently from production.
+4. **Validate changes** before promoting to production.
+
+This capability integrates with Cloudflare's broader [versioning system](/version-management/), allowing you to manage cache configurations alongside other zone settings.
+
+## Benefits
+
+- **Risk-free testing**: Validate configuration changes without impacting production.
+- **Independent purging**: Clear staging cache without affecting live content.
+- **Deployment confidence**: Catch issues before they reach end users.
+- **Team collaboration**: Multiple team members can work on different versions.
+
+## Get started
+
+To get started, refer to the [version management documentation](/version-management/).
+
+:::note[Important limitation]
+
+Cache Reserve is only supported for your production environment. Staged environments can use standard cache functionality, but Cache Reserve persistence is limited to production deployments.
+
+:::

src/content/changelog/cache/2024-11-07-shard-cache-by-cache-key.mdx

@@ -0,0 +1,50 @@
+---
+title: Shard cache using custom cache key values
+description: Enterprise customers can now shard cache using previously restricted accept*, referer, and user-agent headers.
+products:
+  - cache
+date: 2024-11-07
+---
+
+Enterprise customers can now optimize cache hit ratios for content that varies by device, language, or referrer by **sharding cache** using up to ten values from previously restricted headers with [custom cache keys](/cache/how-to/cache-keys/).
+
+## How it works
+
+When configuring [custom cache keys](/cache/how-to/cache-keys/), you can now include values from these headers to create distinct cache entries:
+
+- **`accept*` headers** (for example, `accept`, `accept-encoding`, `accept-language`): Serve different cached versions based on content negotiation.
+- **`referer` header**: Cache content differently based on the referring page or site.
+- **`user-agent` header**: Maintain separate caches for different browsers, devices, or bots.
+
+## When to use cache sharding
+
+- Content varies significantly by device type (mobile vs desktop).
+- Different language or encoding preferences require distinct responses.
+- Referrer-specific content optimization is needed.
+
+## Example configuration
+
+```json
+{
+  "cache_key": {
+    "custom_key": {
+      "header": {
+        "include": ["accept-language", "user-agent"],
+        "check_presence": ["referer"]
+      }
+    }
+  }
+}
+```
+
+This configuration creates separate cache entries based on the `accept-language` and `user-agent` headers, while also considering whether the `referer` header is present.
+
+## Get started
+
+To get started, refer to the [custom cache keys documentation](/cache/how-to/cache-keys/).
+
+:::note
+
+While cache sharding can improve hit ratios for specific use cases, overly sharding your cache can reduce overall cache efficiency and negatively impact performance. Carefully evaluate whether sharding benefits your specific traffic patterns.
+
+:::

src/content/changelog/cache/2024-11-20-smart-tiered-cache-for-r2.mdx

@@ -0,0 +1,28 @@
+---
+title: Smart Tiered Cache automatically optimizes R2 caching
+description: R2 storage buckets now automatically benefit from Smart Tiered Cache with intelligent Upper Tier selection.
+products:
+  - cache
+date: 2024-11-20
+---
+
+You can now reduce latency and lower R2 egress costs automatically when using [Smart Tiered Cache](/cache/how-to/tiered-cache/) with [R2](/r2/). Cloudflare intelligently selects a tiered data center close to your R2 bucket location, creating an efficient caching topology without additional configuration.
+
+## How it works
+
+When you enable [Smart Tiered Cache](/cache/how-to/tiered-cache/) for zones using [R2](/r2/) as an origin, Cloudflare automatically:
+
+1. **Identifies your R2 bucket location**: Determines the geographical region where your R2 bucket is stored.
+2. **Selects an optimal Upper Tier**: Chooses a data center close to your bucket as the common Upper Tier cache.
+3. **Routes requests efficiently**: All cache misses in edge locations route through this Upper Tier before reaching R2.
+
+## Benefits
+
+- **Automatic optimization**: No manual configuration required.
+- **Lower egress costs**: Fewer requests to R2 reduce egress charges.
+- **Improved hit ratio**: Common Upper Tier increases cache efficiency.
+- **Reduced latency**: Upper Tier proximity to R2 minimizes fetch times.
+
+## Get started
+
+To get started, enable [Smart Tiered Cache](/cache/how-to/tiered-cache/) on your zone using R2 as an origin.

src/content/changelog/cache/2025-01-08-smart-tiered-cache-for-load-balancing.mdx

@@ -0,0 +1,33 @@
+---
+title: Smart Tiered Cache optimizes Load Balancing Pools
+description: Smart Tiered Cache now selects a common tiered data center for Load Balancing Pools to increase cache hit ratio.
+products:
+  - cache
+date: 2025-01-08
+---
+
+You can now achieve higher cache hit rates and reduce origin load when using [Load Balancing](/load-balancing/) with [Smart Tiered Cache](/cache/how-to/tiered-cache/). Cloudflare automatically selects a single, optimal tiered data center for all origins in your Load Balancing Pool.
+
+## How it works
+
+When you use [Load Balancing](/load-balancing/) with [Smart Tiered Cache](/cache/how-to/tiered-cache/), Cloudflare analyzes performance metrics across your pool's origins and automatically selects the optimal Upper Tier data center for the entire pool. This means:
+
+- **Consistent cache location**: All origins in the pool share the same Upper Tier cache.
+- **Higher HIT rates**: Requests for the same content hit the cache more frequently.
+- **Reduced origin requests**: Fewer requests reach your origin servers.
+- **Improved performance**: Faster response times for cache HITs.
+
+## Example workflow
+
+```txt
+Load Balancing Pool: api-pool
+├── Origin 1: api-1.example.com
+├── Origin 2: api-2.example.com
+└── Origin 3: api-3.example.com
+    ↓
+Selected Upper Tier: [Optimal data center based on pool performance]
+```
+
+## Get started
+
+To get started, enable [Smart Tiered Cache](/cache/how-to/tiered-cache/) on your zone and configure your [Load Balancing Pool](/load-balancing/).

src/content/changelog/cache/2025-02-12-configurable-multiplexing-http2-to-origin.mdx

@@ -0,0 +1,35 @@
+---
+title: Configurable multiplexing HTTP/2 to Origin
+description: Enterprise customers can now configure HTTP/2 multiplexing settings to optimize origin connections and improve cache performance.
+products:
+  - cache
+date: 2025-02-12
+---
+
+You can now configure HTTP/2 multiplexing settings for origin connections on Enterprise plans. This feature allows you to optimize how Cloudflare manages concurrent requests over HTTP/2 connections to your origin servers, improving cache efficiency and reducing connection overhead.
+
+## How it works
+
+HTTP/2 multiplexing allows multiple requests to be sent over a single TCP connection. With this configuration option, you can:
+
+1. **Control concurrent streams**: Adjust the maximum number of concurrent streams per connection.
+2. **Optimize connection reuse**: Fine-tune connection pooling behavior for your origin infrastructure.
+3. **Reduce connection overhead**: Minimize the number of TCP connections required between Cloudflare and your origin.
+4. **Improve cache performance**: Better connection management can enhance cache fetch efficiency.
+
+## Benefits
+
+- **Customizable performance**: Tailor multiplexing settings to your origin's capabilities.
+- **Reduced latency**: Fewer connection handshakes improve response times.
+- **Lower origin load**: More efficient connection usage reduces server resource consumption.
+- **Enhanced scalability**: Better connection management supports higher traffic volumes.
+
+## Get started
+
+Enterprise customers can configure HTTP/2 multiplexing settings in the [Cloudflare Dashboard](https://dash.cloudflare.com/) or through our [API](/api/).
+
+:::note[Important consideration]
+
+This setting needs to be tuned carefully for your origin infrastructure. Setting the concurrent stream limit too high can negatively impact performance by saturating the shared TCP connection and overwhelming server processing capacity, leading to increased latency for individual requests.
+
+:::

src/content/changelog/cache/2025-04-04-workers-fetch-api-override-cache-rules.mdx

@@ -0,0 +1,39 @@
+---
+title: Workers Fetch API can override Cache Rules
+description: Customers who use Workers can now programmatically override Cache Rules for their individual requests.
+products:
+  - cache
+date: 2025-04-04
+---
+
+You can now programmatically override Cache Rules using the `cf` object in the `fetch()` command. This feature gives you fine-grained control over caching behavior on a per-request basis, allowing Workers to customize cache settings dynamically based on request properties, user context, or business logic.
+
+## How it works
+
+Using the `cf` object in `fetch()`, you can override specific Cache Rules settings by:
+
+1. **Setting custom cache options**: Pass cache properties in the `cf` object as the second argument to `fetch()` to override default Cache Rules.
+2. **Dynamic cache control**: Apply different caching strategies based on request headers, cookies, or other runtime conditions.
+3. **Per-request customization**: Bypass or modify Cache Rules for individual requests while maintaining default behavior for others.
+4. **Programmatic cache management**: Implement complex caching logic that adapts to your application's needs.
+
+## What can be configured
+
+Workers can override the following Cache Rules settings through the `cf` object:
+
+- **`cacheEverything`**: Treat all content as static and cache all file types beyond the default cached content.
+- **`cacheTtl`**: Set custom time-to-live values in seconds for cached content at the edge, regardless of origin headers.
+- **`cacheTtlByStatus`**: Set different TTLs based on the response status code (for example, `{ "200-299": 86400, 404: 1, "500-599": 0 }`).
+- **`cacheKey`**: Customize cache keys to control which requests are treated as the same for caching purposes (Enterprise only).
+- **`cacheTags`**: Append additional cache tags for targeted cache purging operations.
+
+## Benefits
+
+- **Enhanced flexibility**: Customize cache behavior without modifying zone-level Cache Rules.
+- **Dynamic optimization**: Adjust caching strategies in real-time based on request context.
+- **Simplified configuration**: Reduce the number of Cache Rules needed by handling edge cases programmatically.
+- **Improved performance**: Fine-tune cache behavior for specific use cases to maximize hit rates.
+
+## Get started
+
+To get started, refer to the [Workers Fetch API documentation](/workers/runtime-apis/fetch/) and the [cf object properties documentation](/workers/runtime-apis/request/#the-cf-property-requestinitcfproperties).

src/content/changelog/cache/2025-08-29-smart-tiered-cache-fallback-to-generic.mdx

@@ -0,0 +1,31 @@
+---
+title: Smart Tiered Cache Fallback to Generic
+description: Smart Tiered Cache now falls back to Generic Tiered Cache when origin location cannot be determined, improving cache precision.
+products:
+  - cache
+date: 2025-08-29
+---
+
+[Smart Tiered Cache](/cache/how-to/tiered-cache/#smart-tiered-cache) now falls back to [Generic Tiered Cache](/cache/how-to/tiered-cache/#generic-global-tiered-cache) when the origin location cannot be determined, improving cache precision for your content.
+
+Previously, when Smart Tiered Cache was unable to select the optimal upper tier (such as when origins are masked by Anycast IPs), latency could be negatively impacted. This fallback now uses Generic Tiered Cache instead, providing better performance and cache efficiency.
+
+## How it works
+
+When Smart Tiered Cache falls back to Generic Tiered Cache:
+
+1. **Multiple upper-tiers**: Uses all of Cloudflare's global data centers as a network of upper-tiers instead of a single optimal location.
+2. **Distributed cache requests**: Lower-tier data centers can query any available upper-tier for cached content.
+3. **Improved global coverage**: Provides better cache hit ratios across geographically distributed visitors.
+4. **Automatic fallback**: Seamlessly transitions when origin location cannot be determined, such as with Anycast-masked origins.
+
+## Benefits
+
+- **Preserves high performance during fallback**: Smart Tiered Cache now maintains strong cache efficiency even when optimal upper tier selection is not possible.
+- **Minimizes latency impact**: Automatically uses Generic Tiered Cache topology to keep performance high when origin location cannot be determined.
+- **Seamless experience**: No configuration changes or intervention required when fallback occurs.
+- **Improved resilience**: Smart Tiered Cache remains effective across diverse origin infrastructure, including Anycast-masked origins.
+
+## Get started
+
+This improvement is automatically applied to all zones using [Smart Tiered Cache](/cache/how-to/tiered-cache/). No action is required on your part.

src/content/docs/cache/changelog.mdx

@@ -10,39 +10,3 @@ import { ProductChangelog } from "~/components";
 {/* <!-- Actual content lives in /src/content/changelog/cache/. Update the file there for new entries to appear here */}
 
 <ProductChangelog product="cache" />
-
-## 2025-01-08
-
-**Smart Tiered Cache for Load balancing**
-
-Smart Tiered Cache will now select a common single best Upper Tier for an entire Load Balancing Pool based on Origin performance measurements, increasing the cache HIT ratio.
-
-## 2024-11-20
-
-**Smart Tiered Cache for R2**
-
-R2 now automatically gets tiered cache if using Smart Tiered Cache. We select a data center close to your R2 storage bucket as a common Upper Tier cache.
-
-## 2024-11-07
-
-**Shard Cache by cache key**
-
-For custom cache keys, enterprise customers can now shard their cache using up to three values for previously restricted headers `accept*`, `referer`, and `user-agent`. Sharding the cache can improve cache `HIT` ratio and performance. However, overly sharding your cache, can have the opposite effect.
-
-## 2024-11-07
-
-**Versioning**
-
-Cache now supports versioned environments allowing customers to stage configurations and purge staged environments. Note that Cache Reserve is only supported for your production environment.
-
-## 2024-09-05
-
-**New Cache Rules templates for one-click rule creation**
-
-The new **Rules** > **Templates** page in the Cloudflare dashboard provides one-click templates for creating cache rules, making it easy to optimize your caching strategy. Access these pre-built templates directly from each product's rule builder, and explore the [Examples gallery](/rules/examples/) in the developer documentation for real-world use cases.
-
-## 2024-07-19
-
-**Generic tiered cache**
-
-[Generic Global Tiered Cache](/cache/how-to/tiered-cache/#generic-global-tiered-cache) topology leverages all Cloudflare data centers as upper-tier cache network. It now hashes content within a region reducing duplication in upper-tier caches, which increases cache `HIT` ratio.