docs: Numerous various updates for v2.1

src/docs/markdown/caddyfile/directives.md

@@ -15,6 +15,7 @@ Directive | Description
 **[file_server](/docs/caddyfile/directives/file_server)** | Serve files from disk
 **[handle](/docs/caddyfile/directives/handle)** | A mutually-exclusive group of directives
 **[handle_errors](/docs/caddyfile/directives/handle_errors)** | Defines routes for handling errors
+**[handle_path](/docs/caddyfile/directives/handle_path)** | Like handle, but strips path prefix
 **[header](/docs/caddyfile/directives/header)** | Sets or removes response headers
 **[import](/docs/caddyfile/directives/import)** | Include snippets or files
 **[log](/docs/caddyfile/directives/log)** | Enables access/request logging
@@ -85,12 +86,14 @@ encode
 templates
 
 handle
+handle_path
 route
 
 respond
 reverse_proxy
 php_fastcgi
 file_server
+acme_server
 ```
 
 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/basicauth.md

@@ -8,7 +8,7 @@ Enables HTTP Basic Authentication, which can be used to protect directories and
 
 **Note that basic auth is not secure over plain HTTP.** Use discretion when deciding what to protect with HTTP Basic Authentication.
 
-When a user requests a resource that is protected, the browser will prompt the user for a username and password if they have not already supplied one. If the proper credentials are present in the Authorization header, the server will grant access to the resource. If the header is missing or the credentials are incorrect, the server will respond with HTTP 401 Unauthorized.
+When a user requests a resource that is protected, the browser will prompt the user for a username and password if they have not almdy supplied one. If the proper credentials are present in the Authorization header, the server will grant access to the resource. If the header is missing or the credentials are incorrect, the server will respond with HTTP 401 Unauthorized.
 
 Caddy configuration does not accept plaintext passwords; you MUST hash them before putting them into the configuration. The [`caddy hash-password`](/docs/command-line#caddy-hash-password) command can help with this.
 
@@ -16,13 +16,14 @@ Caddy configuration does not accept plaintext passwords; you MUST hash them befo
 ## Syntax
 
 ```caddy-d
-basicauth [<matcher>] [<hash_algorithm>] {
+basicauth [<matcher>] [<hash_algorithm> [<realm>]] {
 	<username> <hashed_password_base64> [<salt_base64>]
 	...
 }
 ```
 
 - **&lt;hash_algorithm&gt;** is the name of the password hashing algorithm (or KDF) used for the hashes in this configuration. Can be `bcrypt` (default) or `scrypt`.
+- **&lt;realm&gt;** is a custom realm name.
 - **&lt;username&gt;** is a username or user ID.
 - **&lt;hashed_password_base64&gt;** is the base-64 encoding of the hashed password.
 - **&lt;salt_base64&gt;** is the base-64 encoding of the password salt, if an external salt is required.

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

@@ -0,0 +1,43 @@
+---
+title: handle_path (Caddyfile directive)
+---
+
+# handle_path
+
+Same as the [`handle` directive](/docs/caddyfile/directives/handle), but implicitly strips the matched path prefix.
+
+Handling a request matching a certain path (while stripping that path from the request URI) is a common enough use case that it has its own directive for convenience.
+
+
+## Syntax
+
+```caddy-d
+handle_path <path_matcher> {
+	<directives...>
+}
+```
+
+- **<directives...>** is a list of HTTP handler directives or directive blocks, one per line, just like would be used outside of a handle_path block.
+
+Note that only a single path matcher is accepted and required; you cannot use other kinds of matchers with handle_path.
+
+## Examples
+
+This configuration:
+
+```caddy-d
+handle_path /prefix/* {
+	...
+}
+```
+
+is effectively the same as this:
+
+```caddy-d
+handle /prefix/* {
+	uri strip_prefix /prefix
+	...
+}
+```
+
+but the `handle_path` form is slightly more succinct.

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

@@ -10,16 +10,30 @@ Caddy's [reverse_proxy](/docs/caddyfile/directives/reverse_proxy) is capable of
 
 It expects that any `index.php` at the site root acts as a router. If that is not desirable, either perform your own URI rewrite or use something like the [expanded form](#expanded-form) below and customize it to your needs.
 
+It supports all the subdirectives of [reverse_proxy](/docs/caddyfile/directives/reverse_proxy) and passes them through to the underlying reverse_proxy handler, plus a few subdirectives that customize the FastCGI transport specifically.
+
+**Most modern PHP apps work fine without extra subdirectives or customization.** Subdirectives are usually only used in certain edge cases or with legacy PHP apps.
 
 ## Syntax
 
 ```caddy-d
-php_fastcgi [<matcher>] <php-fpm_gateway>
+php_fastcgi [<matcher>] <php-fpm_gateways...> {
+	split <substrings...>
+	env [<key> <value>]
+	root <path>
+	index <filenames...>
+
+	<any other reverse_proxy subdirectives...>
+}
 ```
 
-- **<php-fpm_gateway>** is the address of the FastCGI server.
+- **<php-fpm_gateways...>** are the [addresses](/docs/conventions#network-addresses) of the FastCGI servers.
+- **split** sets the substrings for splitting the URI into two parts. The first matching substring will be used to split the "path info" from the path. The first piece is suffixed with the matching substring and will be assumed as the actual resource (CGI script) name. The second piece will be set to PATH_INFO for the CGI script to use. Default: `.php`
+- **env** sets an extra environment variable to the given value.
+- **root** sets the root folder to the site. Default: [`root` directive](/docs/caddyfile/directives/root).
+- **index** specifies the list of filenames to treat as directory index files. This affects the file matcher in the [expanded form](#expanded-form).
 
-Since this directive is an opinionated wrapper over a reverse proxy, you can open a block and use any of reverse_proxy's subdirectives to customize it.
+Since this directive is an opinionated wrapper over a reverse proxy, you can use any of reverse_proxy's subdirectives to customize it.
 
 
 ## Expanded form

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

@@ -124,7 +124,7 @@ transport http {
 	write_buffer <size>
 	dial_timeout <duration>
 	tls
-	tls_client_auth <cert_file> <key_file>
+	tls_client_auth <automate_name> | <cert_file> <key_file>
 	tls_insecure_skip_verify
 	tls_timeout <duration>
 	tls_trusted_ca_certs <pem_files...>
@@ -138,7 +138,7 @@ transport http {
 - **write_buffer** is the size of the write buffer in bytes.
 - **dial_timeout** is how long to wait when connecting to the upstream socket.
 - **tls** uses HTTPS with the backend. This will be enabled automatically if you specify backends using the `https://` scheme or port `:443`.
-- **tls_client_auth** specifies a certificate and key file to present for TLS client authentication with the backend.
+- **tls_client_auth** enables TLS client authentication one of two ways: (1) by specifying a domain name for which Caddy should obtain a certificate and keep it renewed, or (2) by specifying a certificate and key file to present for TLS client authentication with the backend.
 - **tls_insecure_skip_verify** turns off security. _Do not use in production._
 - **tls_timeout** is a [duration value](/docs/conventions#durations) that specifies how long to wait for the TLS handshake to complete.
 - **tls_trusted_ca_certs** is a list of PEM files that specify CA public keys to trust when connecting to the backend.

src/docs/markdown/caddyfile/matchers.md

@@ -93,7 +93,7 @@ redir /old.html /new.html
 
 Path matcher tokens must start with a forward slash `/`.
 
-[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`; 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`; you might actually want `/foo/*` instead.
 
 
 ### Named matchers
@@ -135,8 +135,6 @@ If the matcher set consists of only one matcher, a one-liner syntax also works:
 reverse_proxy @post localhost:6001
 ```
 
-(One-liner named matchers cannot open a block.)
-
 Like directives, named matcher definitions must go inside the site blocks that use them.
 
 A named 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.

src/docs/markdown/caddyfile/options.md

@@ -40,6 +40,7 @@ Possible options are:
 	}
 	local_certs
 	key_type ed25519|p256|p384|rsa2048|rsa4096
+	auto_https off|disable_redirects
 }
 ```
 
@@ -59,3 +60,4 @@ Possible options are:
 	- **interval** and **burst** allows `<n>` certificate operations within `<duration>` interval.
 - **local_certs** causes all certificates to be issued internally by default, rather than through a (public) ACME CA such as Let's Encrypt. This is useful in development environments.
 - **key_type** specifies the type of key to generate for TLS certificates; only change this if you have a specific need to customize it.
+- **auto_https** configure automatic HTTPS. It can either disable it entirely (`off`) or disable only HTTP-to-HTTPS redirects (`disable_redirects`).

src/docs/markdown/command-line.md

@@ -136,7 +136,8 @@ Prints the environment as seen by caddy, then exits. Can be useful when debuggin
 	[--listen <addr>]
 	[--domain <example.com>]
 	[--browse]
-	[--templates]</code></pre>
+	[--templates]
+	[--access-log]</code></pre>
 
 Spins up a simple but production-ready static file server.
 
@@ -150,6 +151,8 @@ Spins up a simple but production-ready static file server.
 
 `--templates` will enable template rendering.
 
+`--access-log` enables the request/access log.
+
 This command disables the admin API, making it easier to run multiple instances on a local development machine.
 
 
@@ -252,6 +255,7 @@ This command disables the admin API so it is easier to run multiple instances on
 	[--adapter &lt;name&gt;]
 	[--pidfile &lt;file&gt;]
 	[--environ]
+	[--envfile &lt;file&gt;]
 	[--resume]
 	[--watch]</code></pre>
 
@@ -265,6 +269,8 @@ Runs Caddy and blocks indefinitely; i.e. "daemon" mode.
 
 `--environ` prints out the environment before starting. This is the same as the `caddy environ` command, but does not exit after printing.
 
+`--envfile` loads environment variables from the specified file.
+
 `--resume` uses the last loaded configuration, overriding the `--config` flag (if present) if a previous config was saved. Using this flag guarantees config durability through machine reboots or process restarts. It is most useful in [API](/docs/api)-heavy deployments.
 
 `--watch` will watch the config file and automatically reload it after it changes. ⚠️ This feature is intended for use only in local development environments!

src/docs/markdown/extending-caddy/namespaces.md

@@ -21,7 +21,7 @@ caddy.storage | [`caddy.StorageConverter`](https://pkg.go.dev/github.com/caddyse
 http.authentication.hashes | [`caddyauth.Comparer`](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/caddyauth?tab=doc#Comparer) | Password hashers/comparers
 http.authentication.providers | [`caddyauth.Authenticator`](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/caddyauth?tab=doc#Authenticator) | HTTP authentication providers
 http.handlers | [`caddyhttp.MiddlewareHandler`](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp?tab=doc#MiddlewareHandler) | HTTP handlers
-http.matchers | [`caddyhttp.RequestMatcher`](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp?tab=doc#RequestMatcher) | HTTP request matchers
+http.matchers | [`caddyhttp.RequestMatcher`](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp?tab=doc#RequestMatcher) | HTTP request matchers<br><i>⚠️ Subject to change</i>
 http.reverse_proxy.circuit_breakers | [`reverseproxy.CircuitBreaker`](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/reverseproxy?tab=doc#CircuitBreaker) | Reverse proxy circuit breakers
 http.reverse_proxy.selection_policies | [`reverseproxy.Selector`](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/reverseproxy?tab=doc#Selector) | Load balancing selection policies<br><i>⚠️ Subject to change</i>
 http.reverse_proxy.transport | [`http.RoundTripper`](https://pkg.go.dev/net/http?tab=doc#RoundTripper) | HTTP reverse proxy transports