2.5.2 docs (#247)

* docs: Changes for v2.5.2 release

* docs: Remove -X POST

Curl automatically uses POST for -d and --data-binary.

I intentionally left it in to be explicit to learners, but
maybe best practices are better.

* api: /adapt endpoint and Etag usage

* api: Minor tweaks

* Alright fine

* Clarify Etag usage

* CEL embedded matchers

* Oops

* Lots more adjustments

Co-authored-by: Francis Lavoie <lavofr@gmail.com>

src/docs/markdown/caddyfile/directives/handle_errors.md

@@ -8,7 +8,7 @@ Sets up error handlers.
 
 When the normal HTTP request handlers return an error, normal processing stops and the error handlers are invoked. Error handlers form a route which is just like normal routes, and they can do anything that normal routes can do. This enables great control and flexibility when handling errors during HTTP requests. For example, you can serve static error pages, templated error pages, or reverse proxy to another backend to handle errors.
 
-A request's context is carried into error routes, so any values set on the request context such as [site root](root) will be preserved in error handlers, too. Additionally, new placeholders are available when handling errors. [The JSON docs for an HTTP server's error routes](/docs/json/apps/http/servers/errors/#routes) describe these placeholders. The `handle_errors` directive simply adds error routes, so you can use those placeholders within a `handle_errors` block.
+A request's context is carried into error routes, so any values set on the request context such as [site root](root) or [vars](vars) will be preserved in error handlers, too. Additionally, [new placeholders](#placeholders) are available when handling errors.
 
 Note that certain directives, for example [`reverse_proxy`](reverse_proxy) which may write a response with an HTTP status which is classified as an error, will _not_ trigger the error routes.
 
@@ -23,17 +23,29 @@ handle_errors {
 }
 ```
 
-- **<directives...>** is a list of HTTP handler directives, directive blocks, or matchers; one per line.
+- **<directives...>** is a list of HTTP handler [directives](/docs/caddyfile/directives) and [matchers](/docs/caddyfile/matchers), one per line.
 
 
+## Placeholders
+
+The following placeholders are available while handling errors. They are [Caddyfile shorthands](/docs/caddyfile/concepts#placeholders) for the full placeholders which can be found in [the JSON docs for an HTTP server's error routes](/docs/json/apps/http/servers/errors/#routes).
+
+| Placeholder | Description |
+|---|---|
+| `{err.status_code}` | The recommended HTTP status code |
+| `{err.status_text}` | The status text associated with the recommended status code |
+| `{err.message}` | The error message |
+| `{err.trace}` | The origin of the error |
+| `{err.id}` | An identifier for this occurrence of the error |
+
 
 ## Examples
 
-Custom error pages based on the status code (i.e. a page called `404.html` for 404 errors). Note that [`file_server`](file_server) preserves the error's HTTP status code when run in `handle_errors`:
+Custom error pages based on the status code (i.e. a page called `404.html` for 404 errors). Note that [`file_server`](file_server) preserves the error's HTTP status code when run in `handle_errors` (assumes you set a [site root](/docs/caddyfile/directives/root) in your site beforehand):
 
 ```caddy-d
 handle_errors {
-	rewrite * /{http.error.status_code}.html
+	rewrite * /{err.status_code}.html
 	file_server
 }
 ```
@@ -52,9 +64,9 @@ Reverse proxy to a professional server that is highly qualified for handling HTT
 
 ```caddy-d
 handle_errors {
-	rewrite * /{http.error.status_code}
+	rewrite * /{err.status_code}
 	reverse_proxy https://http.cat {
-		header_up Host http.cat
+		header_up Host {upstream_hostport}
 	}
 }
 ```
@@ -63,17 +75,26 @@ Simply use [`respond`](/docs/caddyfile/directives/respond) to return the error c
 
 ```caddy-d
 handle_errors {
-	respond "{http.error.status_code} {http.error.status_text}"
+	respond "{err.status_code} {err.status_text}"
 }
 ```
 
-To handle specific error codes differently, use an [`expression`](/docs/caddyfile/matchers#expression) matcher:
+To handle specific error codes differently, use an [`expression`](/docs/caddyfile/matchers#expression) matcher, using [`handle`](/docs/caddyfile/directives/handle) for mutual exclusivity:
 
 ```caddy-d
 handle_errors {
-	@4xx expression `{http.error.status_code} >= 400 && {http.error.status_code} < 500`
-	respond @4xx "It's a 4xx error!"
+	@404-410 expression `{err.status_code} in [404, 410]`
+	handle @404-410 {
+		respond "It's a 404 or 410 error!"
+	}
 
-	respond "It's not a 4xx error."
+	@5xx expression `{err.status_code} >= 500 && {err.status_code} < 600`
+	handle @5xx {
+		respond "It's a 5xx error."
+	}
+
+	handle {
+		respond "It's another error"
+	}
 }
 ```