docs: caddyfile: Add page just about request matchers

src/docs/markdown/caddyfile.md

@@ -27,6 +27,7 @@ The basic idea is that you first type the address of your site, then the feature
 - #### [Full Caddyfile tutorial](/docs/caddyfile-tutorial)
 - #### [Caddyfile concepts](/docs/caddyfile/concepts)
 - #### [Directives](/docs/caddyfile/directives)
+- #### [Request matchers](/docs/caddyfile/matchers)
 - #### [Global options](/docs/caddyfile/options)
 <!-- - #### [Caddyfile specification](/docs/caddyfile/spec) TODO: Finish this -->
 

src/docs/markdown/caddyfile/concepts.md

@@ -156,6 +156,7 @@ Notice how the commas indicate the continuation of addresses.
 An address must be unique; you cannot specify the same address more than once.
 
 
+
 ## Matchers
 
 By default, a directive that injects an HTTP handler applies to all requests (unless otherwise documented).
@@ -170,6 +171,7 @@ To limit a directive's scope, use a **matcher token** immediately after the dire
 
 Matcher tokens are usually optional. If a matcher token is omitted, it is the same as a wildcard matcher (`*`).
 
+
 ### Wildcard matcher
 
 The wildcard matcher `*` matches all requests, and is only needed if a matcher token is required. For example, if the first argument you want to give a directive also happens to be a path, it would look exactly like a path matcher! So you can use a wildcard matcher to disambiguate, for example:
@@ -180,6 +182,7 @@ root * /home/www/mysite
 
 Otherwise, this matcher is not often used. It is convenient to omit it when possible; just a matter of preference.
 
+
 ### Path matcher
 
 Because matching by path is so common, a single path matcher can be inlined, like so:
@@ -190,12 +193,12 @@ redir /old-article.html /new-article.html
 
 Path matcher tokens must start with a forward slash `/`.
 
-Note that [path matching](/docs/json/apps/http/servers/routes/match/path/) is an exact match by default; you must append a `*` for a fast prefix match. Be aware that matching `/foo*` will also match `/foobar`; you might actually want `/foo/*` instead.
+[Path matching](/docs/caddyfile/matchers#path) is an exact match by default; you must append a `*` for a fast prefix match. Note that `/foo*` will match `/foo` and `/foo/` as well as `/foobar`; if this is unintended, you might actually want `/foo/*` instead.
 
 
 ### Named matcher
 
-Defining a matcher with a unique name gives you more flexibility:
+Defining a matcher with a unique name gives you more flexibility, allowing you to combine [any available matchers](/docs/caddyfile/matchers):
 
 ```
 @name {
@@ -215,34 +218,12 @@ For example:
 reverse_proxy @websockets localhost:6001
 ```
 
-This example only proxies requests that have a header field named "Connection" containing the word "Upgrade", and another header named "Upgrade" with a value of "websocket".
-
-The following matcher modules are built-in:
-
-```
-@name {
-	file {
-		root <paths>
-		try_files <files>
-		try_policy first_exist|smallest_size|largest_size|most_recent_modified
-    }
-	header <field> <value>
-	header_regexp <field> <regexp>
-	host <hosts...>
-	method <methods...>
-	not {
-		<any other matchers>
-	}
-	path <paths...>
-	path_regexp [<name>] <regexp>
-	protocol http|https|grpc
-	query <key>=<val>...
-	remote_ip <ranges...>
-}
-```
+This proxies only the requests that have a header field named "Connection" containing the word "Upgrade", and another header named "Upgrade" with a value of "websocket".
 
 Like directives, named matcher definitions must go inside the site blocks that use them.
 
+**[View full list of standard request matchers.](/docs/caddyfile/matchers)**
+
 
 ### Matcher examples
 
@@ -252,7 +233,7 @@ This directive applies to all HTTP requests:
 reverse_proxy localhost:9000
 ```
 
-As does this:
+And this is the same:
 
 ```
 reverse_proxy * localhost:9000
@@ -275,6 +256,7 @@ reverse_proxy @post localhost:9000
 
 
 
+
 ## Placeholders
 
 You can use any [Caddy placeholders](/docs/conventions#placeholders) in the Caddyfile, but for convenience you can also use some equivalent shorthand ones:

src/docs/markdown/caddyfile/matchers.md

@@ -0,0 +1,167 @@
+---
+title: Request matchers (Caddyfile)
+---
+
+# Request Matchers
+
+Matchers are used to filter requests.
+
+There are many dimensions across which requests can be matched! This page describes the various ways you can match (i.e. filter or select) requests.
+
+**If you don't know what a matcher is or how to use it, first [visit the "Concepts" page to learn more](/docs/caddyfile/concepts#matchers)**.
+
+
+## Syntax
+
+The matchers documented below should be used within the definition of [named matchers](/docs/caddyfile/concepts#named-matcher), in other words, within:
+
+```
+@name {
+	# here
+}
+```
+
+A matcher definition constitutes a _matcher set_. Matchers in a set are AND'ed together; i.e. all must match. For example, if you have both a `header` and `path` matcher in the set, both must match.
+
+For most matchers that accept multiple values, those values are OR'ed; i.e. one must match in order for the matcher to match.
+
+## Standard matchers
+
+Full matcher documentation can be found [in each respective matcher module's docs](/docs/json/apps/http/servers/routes/match/).
+
+- [file](#file)
+- [header](#header)
+- [header_regexp](#header_regexp)
+- [host](#host)
+- [method](#method)
+- [not](#not)
+- [path](#path)
+- [path_regexp](#path_regexp)
+- [protocol](#protocol)
+- [query](#query)
+- [remote_ip](#remote_ip)
+
+
+### file
+
+```
+file {
+	root      <paths>
+	try_files <files...>
+	try_policy first_exist|smallest_size|largest_size|most_recent_modified
+}
+```
+
+By files.
+
+- `root` defines the directory in which to look for files. Default is the current working directory, or the `root` [variable](https://caddyserver.com/docs/json/apps/http/servers/errors/routes/handle/vars/) (`{http.vars.root}`) if set.
+- `try_files` checks files in its list that match the try_policy.
+- `try_policy` specifies how to choose a file. Default is `first_exist`.
+	- `first_exist` checks for file existence. The first file that exists is selected.
+	- `smallest_size` chooses the file with the smallest size.
+	- `largest_size` chooses the file with the largest size.
+	- `most_recent_modified` chooses the file that was most recently modified.
+
+
+### header
+
+```
+header <field> <value>
+```
+
+By request header fields.
+
+- `<field>` is the name of the HTTP header field to check.
+- `<value>` is the value the field must have to match.
+	- If prefixed with `*`, it performs a fast suffix match.
+	- If suffixed with `*`, it performs a fast prefix match.
+	- If enclosed by `*`, it performs a fast substring match.
+	- Otherwise, it is a fast exact match.
+
+
+### header_regexp
+
+```
+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.
+
+
+### host
+
+```
+host <hosts...>
+```
+
+Matches request by the `Host` header field of the request. It is not common to use this in the Caddyfile, since most site blocks already indicate hosts in the address of the site. This matcher is mostly used in site blocks that don't define specific hostnames.
+
+
+### method
+
+```
+method <verbs...>
+```
+
+By the method (verb) of the HTTP request. Verbs should be uppercase, like `POST`.
+
+
+### not
+
+```
+not {
+	<any other matchers...>
+}
+```
+
+Encloses other matchers and negates their result.
+
+
+### path
+
+```
+path <paths...>
+```
+
+By request path, meaning the path component of the request's URI. Path matches are exact, but wildcards `*` may be used:
+
+- At the end, for a prefix match (`/prefix/*`)
+- At the beginning, for a suffix match (`*.suffix`)
+- On both sides, for a substring match (`*/contains/*`)
+- In the middle, for a globular match (`/accounts/*/info`)
+
+
+### path_regexp
+
+```
+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.
+
+
+### protocol
+
+```
+protocol http|https|grpc
+```
+
+By request protocol.
+
+
+### query
+
+```
+query <key>=<val>...
+```
+
+By query string parameters. Should be a sequence of `key=value` pairs.
+
+
+### remote_ip
+
+```
+remote_ip <ranges...>
+```
+
+By remote (client) IP address. Accepts exact IPs or CIDR ranges.