From a06fe76b582014eb1d2cc0369c0ee2d8e53b6dce Mon Sep 17 00:00:00 2001
From: "claude[bot]" <41898282+claude[bot]@users.noreply.github.com>
Date: Wed, 5 Aug 2026 07:11:16 +0000
Subject: [PATCH] docs(sitemaps): document new
 wpseo_disable_xml_sitemap_cache_priming filter

Yoast SEO 28.3-RC2 adds a new filter that lets integrators opt out of
the bulk cache priming introduced for sitemap performance.
---
 docs/features/xml-sitemaps/api.md | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/docs/features/xml-sitemaps/api.md b/docs/features/xml-sitemaps/api.md
index 59421e3f..9aaf6d74 100644
--- a/docs/features/xml-sitemaps/api.md
+++ b/docs/features/xml-sitemaps/api.md
@@ -195,6 +195,28 @@ function filter_wpseo_sitemap_urlimages_front_page( $images ) {
 add_filter( 'wpseo_sitemap_urlimages_front_page', 'filter_wpseo_sitemap_urlimages_front_page' );
 ```
 
+## Performance
+
+### Disable cache priming for sitemap generation
+
+By default, Yoast SEO primes the post, term, and featured-image caches in bulk before generating each sitemap batch. This avoids one database query per post on setups without a persistent object cache, but can occasionally interfere with custom caching layers. Use this filter to opt out of the bulk priming when needed.
+
+```php
+<?php
+/**
+ * Disables bulk cache priming during XML sitemap generation.
+ *
+ * @param bool $disable Whether to disable cache priming. Defaults to false.
+ *
+ * @return bool
+ */
+function disable_sitemap_cache_priming( $disable ) {
+    return true;
+}
+
+add_filter( 'wpseo_disable_xml_sitemap_cache_priming', 'disable_sitemap_cache_priming' );
+```
+
 ## Miscellaneous
 
 ### Alter the URL of an entry