jasperf · Oct 28, 2026 · Oct 28, 2026 · Oct 28, 2026 · Oct 28, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Removed
 
+- **The Nginx guides**, now two new posts and one existing post on wpvilla.in: [serving WebP and AVIF through Accept-header negotiation](https://wpvilla.in/serve-webp-avif-nginx-trellis-accept-header-bedrock-uploads/), [browser caching headers as a global include](https://wpvilla.in/nginx-browser-caching-headers-trellis-all-includes-expires/) and [the redirect provision tag and query string](https://wpvilla.in/trellis-nginx-redirect-not-deployed-query-string-dropped/). The four READMEs under `docs/nginx/` are gone; the `.conf.j2` templates stay, and each now opens with a link to its post. The WebP/AVIF template is now `docs/nginx/image-optimization/nginx-includes/all/00-webp-avif.conf.j2`, rewritten after testing it against Nginx: the old file failed `nginx -t` as a site include (`map` is not allowed in a server block), served `photo.webp` instead of the documented `photo.jpg.webp`, and lost to the caching include's image block. It is now a global include that loads first, uses `set`/`if` instead of `map`, and sets its own expiry; rename existing `photo.webp` files to `photo.jpg.webp`. Site includes live in a folder named after the site key; the guides' `nginx_includes` setting does not exist. The browser caching guide had documented 30-day and 7-day durations while the template sets one year; the post describes the template. The generic redirect best-practice and rollback sections are not carried over.
 - **The troubleshooting guides**, now covered on wpvilla.in: [PHP-FPM memory exhaustion](https://wpvilla.in/debugging-php-fpm-memory-exhaustion-wordpress-woocommerce-trellis/), [mail that never arrives or bounces](https://wpvilla.in/trellis-mail-not-sending-smtp-config-reset-and-bounces/), [the MariaDB failure at "Set root user password"](https://wpvilla.in/trellis-provision-set-root-user-password-fails-mariadb-provider-plugins/) and a new post on [the OOM killer, cron and the unlimited PHP CLI memory limit](https://wpvilla.in/linux-oom-killer-wordpress-cron-php-cli-memory-limit-trellis/). `docs/troubleshooting/` is gone, and the README, `AGENTS.md` and `CLAUDE.md` no longer point at it. The generic MariaDB diagnostics and the PHP-FPM sizing tables are not carried over; they stay in git history.
 - **The security guides**, now four posts on wpvilla.in: [the two scanners and checksum verification](https://wpvilla.in/wordpress-malware-scanners-targeted-general-checksum-verification/), [reading scan results](https://wpvilla.in/reading-malware-scan-results-false-positives-wordpress-hardening/), [a permanent Nginx deny list](https://wpvilla.in/nginx-deny-list-trellis-cidr-whitelist-self-lockout/) and [a Trellis security routine](https://wpvilla.in/trellis-wordpress-security-routine-abuseipdb-fail2ban/), plus the existing [fail2ban post](https://wpvilla.in/fail2ban-wordpress-wp-login-trellis-nginx-deny-list/). The `README`, `SECURITY-GUIDE` and `SCANNER-SUMMARY` guides in `wp-cli/security/` and the `README`, `FAIL2BAN` and `MANUAL-IP-BLOCKING` guides in `trellis/security/` are gone; the scanners and the AbuseIPDB scripts stay. The scanner wrapper's closing hint now names the post.
 - **The provisioning and updater guides**, now four posts on wpvilla.in: [a new Mac for Trellis](https://wpvilla.in/new-mac-trellis-development-setup-lima-composer-node/), [cloning an existing project](https://wpvilla.in/clone-trellis-bedrock-project-lima-vm-first-provision/), [updating Trellis](https://wpvilla.in/update-trellis-without-losing-customisations-rsync-excludes/) and [provision tags and the PHP upgrade](https://wpvilla.in/trellis-provision-tags-php-version-upgrade-checklist/). The cron guide is covered by the existing [WP-Cron interval post](https://wpvilla.in/trellis-wp-cron-interval-scheduled-posts-late-cron-interval/). `trellis/provision/` is gone, as are the updater README and `manual-update.md`; the `trellis-updater` script stays.

diff --git a/CLAUDE.md b/CLAUDE.md
@@ -37,7 +37,7 @@ This is a collection of tools, scripts, and documentation for WordPress operatio
   runnable commands and so have no CLI category of their own:
   - `docs/dev/` - Design and planning docs for wp-ops itself. New ones go here, not at the `docs/` top level
   - `docs/cli/` - How the `wp-ops` binary works: usage reference (categories, platforms, completion, guide search) and the trellis-cli plugin
-  - `docs/nginx/` - Web server configs: `browser-caching/`, `image-optimization/`, `redirects/` (guides plus the `.conf.j2` templates they describe)
+  - `docs/nginx/` - Web server configs: `browser-caching/`, `image-optimization/`, `redirects/` (the `.conf.j2` templates; each header links its wpvilla.in post)
   - `docs/bedrock/` - Bedrock/Composer workflows: local package development, and the standard `wp-cli.yml` for Bedrock path setup
   - `docs/wordpress-utilities/` - Copy-paste-into-a-project components and reference material: `snippets/`, `speed-optimization/`
 
@@ -251,9 +251,10 @@ When updating post content via WP-CLI:
 ### Nginx Configuration
 
 Custom Nginx includes (browser caching, image optimization) must be:
-1. Copied to Trellis `nginx-includes/` directory
-2. Referenced in `wordpress_sites.*.nginx_includes` configuration
-3. Applied via `trellis provision <environment>`
+1. Copied to a Trellis `nginx-includes/` directory: `all/` for every site, or a folder named after the site key in `wordpress_sites.yml` for one site (there is no `nginx_includes` setting; Trellis only reads those folders)
+2. Applied via `trellis provision --tags nginx-includes <environment>`
+
+Includes are read inside the server block in alphabetical order, so `map` is not allowed there and the first matching regex `location` wins.
 
 ## Development Workflow
 

diff --git a/README.md b/README.md
@@ -134,7 +134,7 @@ sites are run with:
 | **Monitoring** | AI-crawler traffic, error surfacing, traffic by country, cron-scheduled reports | [→](trellis/monitoring/README.md) |
 | **Security** | Malware scanners with checksum verification, fail2ban, manual IP blocking, AbuseIPDB lookup | [routine](https://wpvilla.in/trellis-wordpress-security-routine-abuseipdb-fail2ban/) · [scanners](https://wpvilla.in/wordpress-malware-scanners-targeted-general-checksum-verification/) |
 | **Content & SEO** | Page creation, block pattern validation, redirect/schema/orphan-page audits | [SEO](wp-cli/seo/README.md) |
-| **Nginx** | WebP/AVIF serving, browser caching and redirect templates for Trellis `nginx-includes/` | [images](docs/nginx/image-optimization/README.md) · [caching](docs/nginx/browser-caching/README.md) · [redirects](docs/nginx/redirects/README.md) |
+| **Nginx** | WebP/AVIF serving, browser caching and redirect templates for Trellis `nginx-includes/` [images](https://wpvilla.in/serve-webp-avif-nginx-trellis-accept-header-bedrock-uploads/) · [caching](https://wpvilla.in/nginx-browser-caching-headers-trellis-all-includes-expires/) · [redirects](https://wpvilla.in/trellis-nginx-redirect-not-deployed-query-string-dropped/) |
 | **Bedrock** | Testing unreleased packages via Composer `path` repos, standard `wp-cli.yml` | [packages](docs/bedrock/local-package-development/README.md) · [wp-cli.yml](docs/bedrock/wp-cli-config/README.md) |
 | **Scripts & guides** | Theme sync, PR helpers, WP-CLI snippets for Bedrock | [scripts](scripts/README.md) · [snippets](docs/wordpress-utilities/snippets/README.md) |
 

diff --git a/docs/nginx/README.md b/docs/nginx/README.md
diff --git a/docs/nginx/browser-caching/README.md b/docs/nginx/browser-caching/README.md
diff --git a/docs/nginx/browser-caching/nginx-includes/all/assets-expiry.conf.j2 b/docs/nginx/browser-caching/nginx-includes/all/assets-expiry.conf.j2
@@ -1,3 +1,7 @@
+# Guide: https://wpvilla.in/nginx-browser-caching-headers-trellis-all-includes-expires/
+# Global include: nginx-includes/all/, no wordpress_sites.yml entry needed.
+# Loads after 00-webp-avif.conf (alphabetical), so keep the WebP include first.
+
 # Nginx configuration for browser caching of static assets
 
 # Settings for SVG files (moved before general static files to take precedence)

diff --git a/docs/nginx/image-optimization/README.md b/docs/nginx/image-optimization/README.md
diff --git a/docs/nginx/image-optimization/nginx-includes/all/00-webp-avif.conf.j2 b/docs/nginx/image-optimization/nginx-includes/all/00-webp-avif.conf.j2
@@ -0,0 +1,27 @@
+# Serves photo.jpg.webp / photo.jpg.avif in place of photo.jpg when the browser
+# accepts them and the file sits next to the original.
+# Guide: https://wpvilla.in/serve-webp-avif-nginx-trellis-accept-header-bedrock-uploads/
+# Global include. The 00- prefix makes it load before assets-expiry.conf (includes
+# are read alphabetically and the first matching regex location wins), so it sets
+# its own expiry. No wordpress_sites.yml entry is needed.
+#
+# set/if instead of map: includes land inside the server block, where map is not allowed.
+
+location ~* ^/app/uploads/.+\.(jpg|jpeg|png)$ {
+    expires 1y;
+    add_header Vary Accept;
+
+    set $avif_suffix ".none";
+    set $webp_suffix ".none";
+    if ($http_accept ~* "image/avif") { set $avif_suffix ".avif"; }
+    if ($http_accept ~* "image/webp") { set $webp_suffix ".webp"; }
+
+    if (-f $document_root$uri$avif_suffix) {
+        rewrite ^ $uri$avif_suffix break;
+    }
+    if (-f $document_root$uri$webp_suffix) {
+        rewrite ^ $uri$webp_suffix break;
+    }
+
+    try_files $uri =404;
+}