docs: Some cleanup, some v2.4.0 additions

- Add `abort` directive docs
- Add a note in `handle` to cross-link to `handle_path`
- Add another example in `handle_errors` that shows how an `expression` matcher can be used to pair with it
- Add a cat emoji to handle_errors because 😸
- Add `file_server` to one of the `php_fastcgi` examples, it's rare that you'll ever use it without `file_server` so might as well include it there
- Add a TOC to `reverse_proxy` cause it's such a long page. Maybe we'll add one to other pages as well, but TBD
- Clarify the upstream address stuff a bit after some discussion in https://caddy.community/t/reverse-proxy-with-multiple-different-upstreams-with-paths/11512/12 and mention `rewrite` as the alternative
- Use the `{re.*.*}` shortcut in the Caddyfile matcher docs, links to the placeholder mapping to let people trace where that comes from

src/docs/markdown/caddyfile/directives.md

@@ -103,6 +103,7 @@ reverse_proxy
 php_fastcgi
 file_server
 acme_server
+abort
 ```
 
 You can override/customize this ordering by using the [`order` global option](/docs/caddyfile/options) or the [`route` directive](/docs/caddyfile/directives/route).

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

@@ -15,8 +15,18 @@ abort [<matcher>]
 
 ## Examples
 
-Abort all requests for paths starting with `/foo`:
+Forcefully close a connection received for unknown domains when using a wildcard certificate:
 
-```caddy-d
-abort /foo*
-```
+```caddy
+*.example.com {
+    @foo host foo.example.com
+    handle @foo {
+        respond "This is foo!" 200
+    }
+
+    # Unhandled domains fall through to here, but we don't want to accept their requests
+    handle {
+        abort
+    }
+}
+```

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

@@ -8,6 +8,10 @@ Evaluates a group of directives mutually exclusively from other `handle` blocks
 
 The `handle` directive is kind of similar to the `location` directive from nginx config: the first matching `handle` block will be evaluated. Handle blocks can be nested if needed. Only HTTP handler directives can be used inside handle blocks.
 
+<aside class="tip">
+	See also the [`handle_path`](/docs/caddyfile/directives/handle_path) directive if you need to strip the matched path prefix.
+</aside>
+
 ## Syntax
 
 ```caddy-d

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

@@ -26,7 +26,7 @@ handle_errors {
 
 Custom error pages based on the status code (i.e. a page called `404.html` for 404 errors):
 
-```caddy
+```caddy-d
 handle_errors {
 	rewrite * /{http.error.status_code}.html
 	file_server
@@ -35,7 +35,7 @@ handle_errors {
 
 A single error page that uses [`templates`](/docs/caddyfile/directives/templates) to write a custom error message:
 
-```caddy
+```caddy-d
 handle_errors {
 	rewrite * /error.html
 	templates
@@ -43,9 +43,9 @@ handle_errors {
 }
 ```
 
-Reverse proxy to a professional server that is highly qualified for handling HTTP errors and improving your day:
+Reverse proxy to a professional server that is highly qualified for handling HTTP errors and improving your day 😸:
 
-```caddy
+```caddy-d
 handle_errors {
 	rewrite * /{http.error.status_code}
 	reverse_proxy https://http.cat {
@@ -56,8 +56,19 @@ handle_errors {
 
 Simply use [`respond`](/docs/caddyfile/directives/respond) to return the error code and name
 
-```caddy
+```caddy-d
 handle_errors {
 	respond "{http.error.status_code} {http.error.status_text}"
 }
 ```
+
+To handle specific error codes differently, use an [`expression`](/docs/caddyfile/matchers#expression) matcher:
+
+```caddy-d
+handle_errors {
+	@4xx expression `{http.error.status_code} >= 400 && {http.error.status_code} < 500`
+	respond @4xx "It's a 4xx error!"
+
+	respond "It's not a 4xx error."
+}
+```

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

@@ -97,9 +97,10 @@ When using php-fpm listening via a unix socket:
 php_fastcgi unix//run/php/php7.4-fpm.sock
 ```
 
-The [`root` directive](/docs/caddyfile/directives/root) is often used to specify the directory containing the PHP scripts:
+The [`root` directive](/docs/caddyfile/directives/root) is often used to specify the directory containing the PHP scripts, and the [`file_server` directive](/docs/caddyfile/directives/file_server) to serve static files:
 
 ```caddy-d
 root * /var/www/html
 php_fastcgi 127.0.0.1:9000
+file_server
 ```

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

@@ -6,6 +6,17 @@ title: reverse_proxy (Caddyfile directive)
 
 Proxies requests to one or more backends with configurable transport, load balancing, health checking, header manipulation, and buffering options.
 
+- [Syntax](#syntax)
+- [Upstreams](#upstreams)
+- [Load balancing](#load-balancing)
+  - [Active health checks](#active-health-checks)
+  - [Passive health checks](#passive-health-checks)
+- [Streaming](#streaming)
+- [Headers](#headers)
+- [Transports](#transports)
+  - [The `http` transport](#the-http-transport)
+  - [The `fastcgi` tranport](#the-fastcgi-transport)
+- [Examples](#examples)
 
 ## Syntax
 
@@ -67,7 +78,11 @@ Upstream addresses can take the form of a conventional [Caddy network address](/
 - `srv+http://internal.service.consul`
 - `srv+https://internal.service.consul`
 
-Note: Schemes cannot be mixed, since they modify the common transport configuration (a TLS-enabled transport cannot carry both HTTPS and plaintext HTTP). Specifying ports 80 and 443 are the same as specifying the HTTP and HTTPS schemes, respectively. Any explicit transport configuration will not be overwritten, and omitting schemes or using other ports will not assume a particular transport. Additionally, schemes cannot contain paths or query strings, as that would imply simultaneous rewriting the request while proxying, which behavior is not defined or supported. If the address is not a URL (i.e. does not have a scheme), then placeholders can be used, but this makes the upstream dynamic.
+Note: Schemes cannot be mixed, since they modify the common transport configuration (a TLS-enabled transport cannot carry both HTTPS and plaintext HTTP). Specifying ports 80 and 443 are the same as specifying the HTTP and HTTPS schemes, respectively. Any explicit transport configuration will not be overwritten, and omitting schemes or using other ports will not assume a particular transport.
+
+Additionally, upstream addresses cannot contain paths or query strings, as that would imply simultaneous rewriting the request while proxying, which behavior is not defined or supported. You may use the [`rewrite`](/docs/caddyfile/directives/rewrite) directive should you need this.
+
+If the address is not a URL (i.e. does not have a scheme), then placeholders can be used, but this makes the upstream dynamic.
 
 ### Load balancing
 

src/docs/markdown/caddyfile/matchers.md

@@ -283,13 +283,13 @@ Match requests that do not have the `Foo` header field at all:
 header_regexp [<name>] <field> <regexp>
 ```
 
-Like `header`, but supports regular expressions. Capture groups can be accessed via placeholder like `{http.regexp.name.capture_group}` where `name` is the name of the regular expression (optional, but recommended) and `capture_group` is either the name or number of the capture group in the expression. Capture group `0` is the full regexp match, `1` is the first capture group, `2` is the second capture group, and so on.
+Like `header`, but supports regular expressions. Capture groups can be accessed via [placeholder](/docs/caddyfile/concepts#placeholders) like `{re.name.capture_group}` where `name` is the name of the regular expression (optional, but recommended) and `capture_group` is either the name or number of the capture group in the expression. Capture group `0` is the full regexp match, `1` is the first capture group, `2` is the second capture group, and so on.
 
 Only one regular expression is supported per header field. Multiple different fields will be AND'ed.
 
 #### Example:
 
-Match requests where the Cookie header contains `login_` followed by a hex string, with a capture group that can be accessed with `{http.regexp.login.1}`.
+Match requests where the Cookie header contains `login_` followed by a hex string, with a capture group that can be accessed with `{re.login.1}`.
 
 ```caddy-d
 header_regexp login Cookie login_([a-f0-9]+)
@@ -414,13 +414,13 @@ Multiple `path` matchers will be OR'ed together.
 path_regexp [<name>] <regexp>
 ```
 
-Like `path`, but supports regular expressions. Capture groups can be accessed via placeholder like `{http.regexp.name.capture_group}` where `name` is the name of the regular expression (optional, but recommended) and `capture_group` is either the name or number of the capture group in the expression. Capture group `0` is the full regexp match, `1` is the first capture group, `2` is the second capture group, and so on.
+Like `path`, but supports regular expressions. Capture groups can be accessed via [placeholder](/docs/caddyfile/concepts#placeholders) like `{re.name.capture_group}` where `name` is the name of the regular expression (optional, but recommended) and `capture_group` is either the name or number of the capture group in the expression. Capture group `0` is the full regexp match, `1` is the first capture group, `2` is the second capture group, and so on.
 
 There can only be one `path_regexp` matcher per named matcher.
 
 #### Example:
 
-Match requests where the path ends a 6 character hex string followed by `.css` or `.js` as the file extension, with capture groups that can be accessed with `{http.regexp.static.1}` and `{http.regexp.static.2}` for each part enclosed in `( )`, respectively.
+Match requests where the path ends a 6 character hex string followed by `.css` or `.js` as the file extension, with capture groups that can be accessed with `{re.static.1}` and `{re.static.2}` for each part enclosed in `( )`, respectively.
 
 ```caddy-d
 path_regexp static \.([a-f0-9]{6})\.(css|js)$