More docs changes for upcoming v2.5.0 release

src/docs/markdown/caddyfile/concepts.md

@@ -141,15 +141,18 @@ Quotes can be escaped if you need to use quotes in quoted tokens, too:
 directive "\"abc def\""
 ```
 
-Inside quoted tokens, all other characters are treated literally, including spaces, tabs, and newlines.
-
-You can also use a backtick <code>`</code> to quote tokens:
+Inside quoted tokens, all other characters are treated literally, including spaces, tabs, and newlines. Multi-line tokens are possible:
 
 ```caddy-d
-directive `"foo bar"`
+directive "first line
+second line"
 ```
 
-Backtick strings are convenient when tokens contain quote literals, e.g. JSON text.
+You can also use a backtick <code>`</code> to quote tokens; these are convenient when tokens themselves contain double quotes, e.g. JSON text:
+
+```caddy-d
+directive `{"foo": "bar"}`
+```
 
 
 
@@ -254,6 +257,7 @@ You can use any [Caddy placeholders](/docs/conventions#placeholders) in the Cadd
 | `{tls_client_certificate_pem}` | `{http.request.tls.client.certificate_pem}` |
 | `{tls_client_certificate_der_base64}` | `{http.request.tls.client.certificate_der_base64}` |
 | `{upstream_hostport}` | `{http.reverse_proxy.upstream.hostport}` |
+| `{vars.*}` | `{http.vars.*}` |
 
 
 

src/docs/markdown/caddyfile/directives.md

@@ -66,6 +66,7 @@ Directive | Description
 **[tracing](/docs/caddyfile/directives/tracing)** | Integration with OpenTelemetry tracing
 **[try_files](/docs/caddyfile/directives/try_files)** | Rewrite that depends on file existence
 **[uri](/docs/caddyfile/directives/uri)** | Manipulate the URI
+**[vars](/docs/caddyfile/directives/vars)** | Set arbitrary variables
 
 </div>
 
@@ -109,6 +110,7 @@ Many directives manipulate the HTTP handler chain. The order in which those dire
 tracing
 
 map
+vars
 root
 
 header

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

@@ -29,6 +29,8 @@ map [<matcher>] <source> <destinations...> {
 
   As a special case, the Caddyfile parser treats outputs that are a literal hyphen (`-`) as null/nil values. This is useful if you want to fall back to a default value for that particular output in the case of the given input, but want to use non-default values for other outputs.
 
+  The outputs will be type converted if possible; `true` and `false` will be converted to boolean types, and numeric values will be converted to integer or float accordingly. To avoid this conversion, you may wrap the output with [quotes](/docs/caddyfile/concepts#tokens-and-quotes) and they will stay strings.
+
   The number of outputs for each mapping must not exceed the number of destinations; however, for convenience, there may be fewer outputs than destinations, and any missing outputs will be filled in implicitly.
 
   If a regular expression was used as the input, then the capture groups can be referenced with `${group}` where `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.

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

@@ -130,6 +130,7 @@ Obtains certificates using the ACME protocol.
 	trusted_roots <pem_files...>
 	dns <provider_name> [<options>]
 	propagation_timeout <duration>
+	propagation_delay <duration>
 	resolvers <dns_servers...>
 	preferred_chains [smallest] {
 		root_common_name <common_names...>
@@ -149,7 +150,8 @@ Obtains certificates using the ACME protocol.
 - **eab** <span id="eab"/> specifies an External Account Binding which may be required with some ACME CAs.
 - **trusted_roots** <span id="trusted_roots"/> is one or more root certificates (as PEM filenames) to trust when connecting to the ACME CA server.
 - **dns** <span id="dns"/> configures the DNS challenge.
-- **propagation_timeout** <span id="propagation_timeout"/> is a [duration value](/docs/conventions#durations) that sets how long to wait for DNS TXT records to propagate when using the DNS challenge. Default 2 minutes.
+- **propagation_timeout** <span id="propagation_timeout"/> is a [duration value](/docs/conventions#durations) that sets the maximum time to wait for the DNS TXT records to appear when using the DNS challenge. Set to `-1` to disable propagation checks. Default 2 minutes.
+- **propagation_delay** <span id="propagation_delay"/> is a [duration value](/docs/conventions#durations) that sets how long to wait before starting DNS TXT records propagation checks when using the DNS challenge. Default 0 (no wait).
 - **resolvers** <span id="resolvers"/> customizes the DNS resolvers used when performing the DNS challenge; these take precedence over system resolvers or any default ones.
 - **preferred_chains** <span id="preferred_chains"/> specifies which certificate chains Caddy should prefer; useful if your CA provides multiple chains. Use one of the following options:
 	- **smallest** <span id="smallest"/> will tell Caddy to prefer chains with the fewest amount of bytes.

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

@@ -0,0 +1,53 @@
+---
+title: vars (Caddyfile directive)
+---
+
+# vars
+
+Sets one or more variables to a particular value, to be used later in the request handling chain.
+
+The primary way to access variables is with placeholders, which have the form `{vars.variable_name}`, or with the [`vars`](/docs/caddyfile/matchers#vars) and [`vars_regexp`](/docs/caddyfile/matchers#vars_regexp) request matchers.
+
+## Syntax
+
+```caddy-d
+vars [<matcher>] [<name> <value>] {
+    <name> <value>
+    ...
+}
+```
+
+- **&lt;name&gt;** is the variable name to set.
+
+- **&lt;value&gt;** is the value of the variable.
+
+  The value will be type converted if possible; `true` and `false` will be converted to boolean types, and numeric values will be converted to integer or float accordingly. To avoid this conversion, you may wrap the output with [quotes](/docs/caddyfile/concepts#tokens-and-quotes) and they will stay strings.
+
+## Examples
+
+To set a single variable, the value being conditional based on the request path, then responding with the value:
+
+```caddy-d
+vars /foo* isFoo "yep"
+vars isFoo "nope"
+
+respond {vars.isFoo}
+```
+
+To set multiple variables, each converted to the appropriate scalar type:
+
+```caddy-d
+vars {
+	# boolean
+	abc true
+
+	# integer
+	def 1
+
+	# float
+	ghi 2.3
+
+	# string
+	jkl "example"
+}
+```

src/docs/markdown/command-line.md

@@ -179,14 +179,16 @@ This command disables the admin API, making it easier to run multiple instances
 
 ### `caddy fmt`
 
-<pre><code class="cmd bash">caddy fmt [--overwrite] [&lt;path&gt;]</code></pre>
+<pre><code class="cmd bash">caddy fmt [--overwrite] [--diff] [&lt;path&gt;]</code></pre>
 
 Formats or prettifies a Caddyfile, then exits. The result is printed to stdout unless `--overwrite` is used.
 
 `<path>` specifies the path to the Caddyfile. If `-`, the input is read from stdin. If omitted, a file named Caddyfile in the current directory is assumed instead.
 
 `--overwrite` causes the result to be written to the input file instead of being printed to the terminal. If the input is not a regular file, this flag has no effect.
 
+`--diff` causes the output to be compared against the input, and lines will be prefixed with `-` and `+` where they differ. Note that unchanges lines are prefixed with two spaces for alignment, and that this is not a valid patch format; it's just meant as a visual tool.
+
 
 
 
@@ -294,7 +296,7 @@ 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.
+`--envfile` loads environment variables from the specified file, in `KEY=VALUE` format. Comments starting with `#` are supported; keys may be prefixed with `export`; values may be double-quoted (double-quotes within can be escaped); multi-line values are supported.
 
 `--resume` uses the last loaded configuration that was autosaved, overriding the `--config` flag (if present). Using this flag guarantees config durability through machine reboots or process restarts. It is most useful in [API](/docs/api)-centric deployments.