Lots more adjustments

src/docs/markdown/api-tutorial.md

@@ -132,10 +132,14 @@ Using the request URI's path, we can traverse into the config structure and upda
 	-d '"Work smarter, not harder."'
 </code></pre>
 
+
 <aside class="tip">
-	Every time you change the config using the API, Caddy persists a copy of the new config so you can <a href="/docs/command-line#caddy-run"><b>--resume</b> it later</a>!
+
+Every time you change the config using the API, Caddy persists a copy of the new config so you can [**--resume** it later](/docs/command-line#caddy-run)!
+
 </aside>
 
+
 You can verify that it worked with a similar GET request, for example:
 
 <pre><code class="cmd bash">curl localhost:2019/config/apps/http/servers/example/routes</code></pre>
@@ -146,10 +150,14 @@ You should see:
 [{"handle":[{"body":"Work smarter, not harder.","handler":"static_response"}]}]
 ```
 
+
 <aside class="tip">
-	You can use the <a href="https://stedolan.github.io/jq/">jq command</a> to prettify JSON output: <b><code>curl ... | jq</code></b>
+
+You can use the [`jq` command](https://stedolan.github.io/jq/) to prettify JSON output: **`curl ... | jq`**
+
 </aside>
 
+
 <aside class="complete">Traverse config</aside>
 
 **Important note:** This should be obvious, but once you use the API to make a change that is not in your original config file, your config file becomes obsolete. There are a few ways to handle this:
@@ -182,10 +190,14 @@ This adds a property to our handler object: `"@id": "msg"`, so it now looks like
 }
 ```
 
+
 <aside class="tip">
-	<b>@id</b> tags can go in any object and can have any primitive value (usually a string). <a href="/docs/api#using-id-in-json">Learn more</a>
+
+**@id** tags can go in any object and can have any primitive value (usually a string). [Learn more](/docs/api#using-id-in-json)
+
 </aside>
 
+
 We can then access it directly:
 
 <pre><code class="cmd bash">curl localhost:2019/id/msg</code></pre>

src/docs/markdown/api.md

@@ -251,6 +251,7 @@ This section is for all `/config/` endpoints. It is experimental and subject to
 
 </aside>
 
+
 Caddy's config API provides [ACID guarantees](https://en.wikipedia.org/wiki/ACID) for individual requests, but changes that involve more than a single request are subject to collisions or data loss if not properly synchronized.
 
 For example, two clients may `GET /config/foo` at the same time, make an edit within that scope (config path), then call `POST|PUT|PATCH|DELETE /config/foo/...` at the same time to apply their changes, resulting in a collision: either one will overwrite the other, or the second might leave the config in an unintended state since it was applied to a different version of the config than it was prepared against. This is because the changes are not aware of each other.

src/docs/markdown/architecture.md

@@ -18,16 +18,23 @@ Caddy consists of a command, core library, and modules.
 
 The **command** provides the [command line interface](/docs/command-line) you are hopefully familiar with. It's how you launch the process from your operating system. The amount of code and logic here is fairly minimal, and has only what is needed to bootstrap the core in the user's desired way. We intentionally avoid using flags and environment variables for configuration except as they pertain to bootstrapping config.
 
+
 <aside class="tip">
-	Modules can add subcommands to the command line interface! For instance, that's where the <a href="/docs/command-line#caddy-file-server">caddy file-server</a> command comes from. These added commands may have any flags or use any environment variables they want, even though the core Caddy commands minimize their use.
+
+Modules can add subcommands to the command line interface! For instance, that's where the [`caddy file-server`](/docs/command-line#caddy-file-server) command comes from. These added commands may have any flags or use any environment variables they want, even though the core Caddy commands minimize their use.
+
 </aside>
 
+
 The **[core library](https://pkg.go.dev/github.com/caddyserver/caddy/v2?tab=doc)**, or "core" of Caddy, primarily manages configuration. It can [`Run()`](https://pkg.go.dev/github.com/caddyserver/caddy/v2?tab=doc#Run) a new configuration or [`Stop()`](https://pkg.go.dev/github.com/caddyserver/caddy/v2?tab=doc#Stop) a running config. It also provides various utilities, types, and values for modules to use.
 
 **Modules** do everything else. Many modules come built into Caddy, which are called the _standard modules_. These are determined to be the most useful to the most users.
 
+
 <aside class="tip">
-	Sometimes the terms <i>module</i>, <i>plugin</i>, and <i>extension</i> get used interchangably, and usually that's OK. Technically, all modules are plugins, but not all plugins are modules. Modules are specifically a kind of plugin that extends Caddy's <a href="/docs/json/">config structure</a>.
+
+Sometimes the terms *module*, *plugin*, and *extension* get used interchangably, and usually that's OK. Technically, all modules are plugins, but not all plugins are modules. Modules are specifically a kind of plugin that extends Caddy's [config structure](/docs/json/).
+
 </aside>
 
 
@@ -64,7 +71,9 @@ When an app module is started, it initiates the app's module lifecycle.
 
 
 <aside class="tip">
-	If you are a programmer who is building Caddy modules, you can find analogous information in our <a href="/docs/extending-caddy">Extending Caddy</a> guide, but with more focus on code.
+
+If you are a programmer who is building Caddy modules, you can find analogous information in our [Extending Caddy](/docs/extending-caddy) guide, but with more focus on code.
+
 </aside>
 
 
@@ -116,8 +125,11 @@ When it is time for a config to be stopped, all modules get unloaded. If a modul
 
 A module -- or any Caddy plugin -- gets "plugged in" to Caddy by adding an `import` for the module's package. By importing the package, [the module registers itself](https://pkg.go.dev/github.com/caddyserver/caddy/v2?tab=doc#RegisterModule) with the Caddy core, so when the Caddy process starts, it knows each module by name. It can even associate between module values and names, and vice-versa.
 
+
 <aside class="tip">
-	Plugins can be added without modifying the Caddy code base at all. There are instructions <a href="https://github.com/caddyserver/caddy/#with-version-information-andor-plugins">in the readme</a> for doing this!
+
+Plugins can be added without modifying the Caddy code base at all. There are instructions [in the readme](https://github.com/caddyserver/caddy/#with-version-information-andor-plugins) for doing this!
+
 </aside>
 
 

src/docs/markdown/automatic-https.md

@@ -8,7 +8,9 @@ title: "Automatic HTTPS"
 
 Automatic HTTPS provisions TLS certificates for all your sites and keeps them renewed. It also redirects HTTP to HTTPS for you! Caddy uses safe and modern defaults -- no downtime, extra configuration, or separate tooling is required.
 
-<aside class="tip">Caddy innovated automatic HTTPS technology; we've been doing this since the first day it was feasible in 2015. Caddy's HTTPS automation logic is the most mature and robust in the world.</aside>
+<aside class="tip">
+	Caddy innovated automatic HTTPS technology; we've been doing this since the first day it was feasible in 2015. Caddy's HTTPS automation logic is the most mature and robust in the world.
+</aside>
 
 Here's a 28-second video showing how it works:
 
@@ -40,19 +42,24 @@ Here's a 28-second video showing how it works:
 - Caddy serves public DNS names over HTTPS using certificates from a public ACME CA such as [Let's Encrypt](https://letsencrypt.org) or [ZeroSSL](https://zerossl.com).
 	- Examples: `example.com`, `sub.example.com`, `*.example.com`
 
-Caddy keeps all managed certificates renewed and redirects HTTP (default port 80) to HTTPS (default port 443) automatically.
+Caddy keeps all managed certificates renewed and redirects HTTP (default port `80`) to HTTPS (default port `443`) automatically.
 
 **For local HTTPS:**
 
 - Caddy may prompt for a password to install its unique root certificate into your trust store. This happens only once per root; and you can remove it at any time.
-- Any client accessing the site without trusting Caddy's root will show security errors.
+- Any client accessing the site without trusting Caddy's root CA certificate will show security errors.
 
 **For public domain names:**
 
-<aside class="tip">These are common requirements for any basic production website, not just Caddy. The main difference is to set your DNS records properly <b>before</b> running Caddy so it can provision certificates.</aside>
+<aside class="tip">
+
+These are common requirements for any basic production website, not just Caddy. The main difference is to set your DNS records properly **before** running Caddy so it can provision certificates.
+
+</aside>
+
 
 - If your domain's A/AAAA records point to your server,
-- ports 80 and 443 are open externally,
+- ports `80` and `443` are open externally,
 - Caddy can bind to those ports (_or_ those ports are forwarded to Caddy),
 - your [data directory](/docs/conventions#data-directory) is writeable and persistent,
 - and your domain name appears somewhere relevant in the config,
@@ -68,16 +75,17 @@ Because HTTPS utilizes a shared, public infrastructure, you as the server admin
 Caddy implicitly activates automatic HTTPS when it knows a domain name (i.e. hostname) or IP address it is serving. There are various ways to tell Caddy your domain/IP, depending on how you run or configure Caddy:
 
 - A [site address](/docs/caddyfile/concepts#addresses) in the [Caddyfile](/docs/caddyfile)
-- A [host matcher](/docs/json/apps/http/servers/routes/match/host/) in a [route](/docs/modules/http#servers/routes)
+- A [host matcher](/docs/json/apps/http/servers/routes/match/host/) in a [JSON route](/docs/modules/http#servers/routes)
 - Command line flags like [--domain](/docs/command-line#caddy-file-server) or [--from](/docs/command-line#caddy-reverse-proxy)
 - The [automate](/docs/json/apps/tls/certificates/automate/) certificate loader
 
 Any of the following will prevent automatic HTTPS from being activated, either in whole or in part:
 
-- [Explicitly disabling it](/docs/json/apps/http/servers/automatic_https/)
+- Explicitly disabling it [via JSON](/docs/json/apps/http/servers/automatic_https/) or [via Caddyfile](/docs/caddyfile/options#auto-https)
 - Not providing any hostnames or IP addresses in the config
 - Listening exclusively on the HTTP port
-- Manually loading certificates (unless [this config property](/docs/json/apps/http/servers/automatic_https/ignore_loaded_certificates/) is true)
+- Prefixing the [site address](/docs/caddyfile/concepts#addresses) with `http://` in the Caddyfile
+- Manually loading certificates (unless [`ignore_loaded_certificates`](/docs/json/apps/http/servers/automatic_https/ignore_loaded_certificates/) is set)
 
 **Special cases:**
 
@@ -89,8 +97,8 @@ Any of the following will prevent automatic HTTPS from being activated, either i
 When automatic HTTPS is activated, the following occurs:
 
 - Certificates are obtained and renewed for [all domain names](#hostname-requirements)
-- The default port (if any) is changed to the [HTTPS port](/docs/modules/http#https_port) 443
+- The default port (if any) is changed to the [HTTPS port](/docs/modules/http#https_port) `443`
-- HTTP is redirected to HTTPS (this uses [HTTP port](/docs/modules/http#http_port) 80)
+- HTTP is redirected to HTTPS (this uses [HTTP port](/docs/modules/http#http_port) `80`)
 
 Automatic HTTPS never overrides explicit configuration.
 
@@ -126,9 +134,11 @@ The root's private key is uniquely generated using a cryptographically-secure ps
 
 Although Caddy can be configured to sign with the root directly (to support non-compliant clients), this is disabled by default, and the root key is only used to sign intermediates.
 
-The first time a root key is used, Caddy will try to install it into the system's local trust store(s). If it does not have permission to do so, it will prompt for a password. This behavior can be disabled in the configuration if it is not desired.
+The first time a root key is used, Caddy will try to install it into the system's local trust store(s). If it does not have permission to do so, it will prompt for a password. This behavior can be disabled in the configuration if it is not desired. If this fails due to being run as an unprivileged user, you may run [`caddy trust`](/docs/command-line#caddy-trust) to retry installation as a privileged user.
 
-<aside class="tip">It is safe to trust Caddy's root certificate on your own machine as long as your computer is not compromised and your unique root key is not leaked.</aside>
+<aside class="tip">
+	It is safe to trust Caddy's root certificate on your own machine as long as your computer is not compromised and your unique root key is not leaked.
+</aside>
 
 After Caddy's root CA is installed, you will see it in your local trust store as "Caddy Local Authority" (unless you've configured a different name). You can uninstall it any time if you wish (the [`caddy untrust`](/docs/command-line#caddy-untrust) command makes this easy).
 
@@ -161,29 +171,29 @@ The first two challenge types are enabled by default. If multiple challenges are
 
 ### HTTP challenge
 
-The HTTP challenge performs an authoritative DNS lookup for the candidate hostname's A/AAAA record, then requests a temporary cryptographic resource over port 80 using HTTP. If the CA sees the expected resource, a certificate is issued.
+The HTTP challenge performs an authoritative DNS lookup for the candidate hostname's A/AAAA record, then requests a temporary cryptographic resource over port `80` using HTTP. If the CA sees the expected resource, a certificate is issued.
 
-This challenge requires port 80 to be externally accessible. If Caddy cannot listen on port 80, packets from port 80 must be forwarded to Caddy's [HTTP port](/docs/json/apps/http/http_port/).
+This challenge requires port `80` to be externally accessible. If Caddy cannot listen on port 80, packets from port `80` must be forwarded to Caddy's [HTTP port](/docs/json/apps/http/http_port/).
 
 This challenge is enabled by default and does not require explicit configuration.
 
 
 ### TLS-ALPN challenge
 
-The TLS-ALPN challenge performs an authoritative DNS lookup for the candidate hostname's A/AAAA record, then requests a temporary cryptographic resource over port 443 using a TLS handshake containing special ServerName and ALPN values. If the CA sees the expected resource, a certificate is issued.
+The TLS-ALPN challenge performs an authoritative DNS lookup for the candidate hostname's A/AAAA record, then requests a temporary cryptographic resource over port `443` using a TLS handshake containing special ServerName and ALPN values. If the CA sees the expected resource, a certificate is issued.
 
-This challenge requires port 443 to be externally accessible. If Caddy cannot listen on port 443, packets from port 443 must be forwarded to Caddy's [HTTPS port](/docs/json/apps/http/https_port/).
+This challenge requires port `443` to be externally accessible. If Caddy cannot listen on port 443, packets from port `443` must be forwarded to Caddy's [HTTPS port](/docs/json/apps/http/https_port/).
 
 This challenge is enabled by default and does not require explicit configuration.
 
 
 ### DNS challenge
 
-The DNS challenge performs an authoritative DNS lookup for the candidate hostname's TXT records, and looks for a special TXT record with a certain value. If the CA sees the expected value, a certificate is issued.
+The DNS challenge performs an authoritative DNS lookup for the candidate hostname's `TXT` records, and looks for a special `TXT` record with a certain value. If the CA sees the expected value, a certificate is issued.
 
-This challenge does not require any open ports, and the server requesting a certificate does not need to be externally accessible. However, the DNS challenge requires configuration. Caddy needs to know the credentials to access your domain's DNS provider so it can set (and clear) the special TXT records. If the DNS challenge is enabled, other challenges are disabled by default.
+This challenge does not require any open ports, and the server requesting a certificate does not need to be externally accessible. However, the DNS challenge requires configuration. Caddy needs to know the credentials to access your domain's DNS provider so it can set (and clear) the special `TXT` records. If the DNS challenge is enabled, other challenges are disabled by default.
 
-Since ACME CAs follow DNS standards when looking up TXT records for challenge verification, you can use CNAME records to delegate answering the challenge to other DNS zones. This can be used to delegate the `_acme-challenge` subdomain to another zone. This is particularly useful if your DNS provider doesn't provide an API, or isn't supported by one of the DNS plugins for Caddy.
+Since ACME CAs follow DNS standards when looking up `TXT` records for challenge verification, you can use CNAME records to delegate answering the challenge to other DNS zones. This can be used to delegate the `_acme-challenge` subdomain to another zone. This is particularly useful if your DNS provider doesn't provide an API, or isn't supported by one of the DNS plugins for Caddy.
 
 DNS provider support is a community effort. [Learn how to enable the DNS challenge for your provider at our wiki.](https://caddy.community/t/how-to-use-dns-provider-modules-in-caddy-2/8148)
 

src/docs/markdown/build.md

@@ -19,10 +19,14 @@ Build:
 <pre><code class="cmd"><span class="bash">cd caddy/cmd/caddy/</span>
 <span class="bash">go build</span></code></pre>
 
+
 <aside class="tip">
-	Due to <a href="https://github.com/golang/go/issues/29228">a bug in Go</a>, these basic steps do not embed version information. If you want the version (<code>caddy version</code>), you need to compile Caddy as a dependency rather than as the main module. Instructions for this are in Caddy's <a href="https://github.com/caddyserver/caddy/blob/master/cmd/caddy/main.go">main.go</a> file. Or, you can use <a href="#xcaddy"><code>xcaddy</code></a> which automates this.
+
+Due to [a bug in Go](https://github.com/golang/go/issues/29228), these basic steps do not embed version information. If you want the version (`caddy version`), you need to compile Caddy as a dependency rather than as the main module. Instructions for this are in Caddy's [main.go](https://github.com/caddyserver/caddy/blob/master/cmd/caddy/main.go) file. Or, you can use [`xcaddy`](#xcaddy) which automates this.
+
 </aside>
 
+
 ## xcaddy
 
 The [`xcaddy` command](https://github.com/caddyserver/xcaddy) is the easiest way to build Caddy with version information and/or plugins.

src/docs/markdown/caddyfile-tutorial.md

@@ -32,9 +32,12 @@ localhost
 ```
 
 <aside class="tip">
-	If the HTTP and HTTPS ports (80 and 443, respectively) are privileged ports on your OS, you will either need to run with elevated privileges or use a higher port. To use a higher port, just change the address to something like <code>localhost:2015</code> and change the HTTP port using the <a href="/docs/caddyfile/options">http_port</a> Caddyfile option.
+
+If the HTTP and HTTPS ports (80 and 443, respectively) are privileged ports on your OS, you will either need to run with elevated privileges or use a higher port. To use a higher port, just change the address to something like `localhost:2015` and change the HTTP port using the [http_port](/docs/caddyfile/options) Caddyfile option.
+
 </aside>
 
+
 Then hit enter and type what you want it to do. For this tutorial, make your Caddyfile look like this:
 
 ```caddy
@@ -48,18 +51,28 @@ Save that and run Caddy (since this is a training tutorial, we'll use the `--wat
 <pre><code class="cmd bash">caddy run --watch</code></pre>
 
 <aside class="tip">
-	If you get permissions errors, try using a higher port in your address (like <code>localhost:2015</code>) and <a href="/docs/caddyfile/options">change the HTTP port</a>, or run with elevated privileges.
+
+If you get permissions errors, try using a higher port in your address (like `localhost:2015`) and [change the HTTP port](/docs/caddyfile/options), or run with elevated privileges.
+
 </aside>
 
+
 The first time, you'll be asked for your password. This is so Caddy can serve your site over HTTPS.
 
-<aside class="tip">Caddy serves all sites over HTTPS by default as long as a host or IP is part of the site's address. <a href="/docs/automatic-https">Automatic HTTPS</a> can be disabled by prefixing the address with <code>http://</code> explicitly.</aside>
+<aside class="tip">
+
+Caddy serves all sites over HTTPS by default as long as a host or IP is part of the site's address. [Automatic HTTPS](/docs/automatic-https) can be disabled by prefixing the address with `http://` explicitly.
+
+</aside>
+
 
 <aside class="complete">First site</aside>
 
 Open [localhost](https://localhost) in your browser and see your web server working, complete with HTTPS!
 
-<aside class="tip">You might need to restart your browser if you get a certificate error the first time.</aside>
+<aside class="tip">
+	You might need to restart your browser if you get a certificate error the first time.
+</aside>
 
 That's not particularly exciting, so let's change our static response to a [file server](/docs/caddyfile/directives/file_server) with directory listings enabled:
 
@@ -126,7 +139,9 @@ templates
 file_server browse
 ```
 
-<aside class="tip">Browsers don't support Zstandard encodings yet. Hopefully soon!</aside>
+<aside class="tip">
+	Browsers don't support Zstandard encodings yet. Hopefully soon!
+</aside>
 
 
 <aside class="complete">Compression</aside>

src/docs/markdown/caddyfile/concepts.md

@@ -172,17 +172,21 @@ These are examples of valid addresses:
 - `*.example.com`
 - `http://`
 
+
 <aside class="tip">
-	<a href="/docs/automatic-https">Automatic HTTPS</a> is enabled if your site's address contains a hostname or IP address. This behavior is purely implicit, however, so it never overrides any explicit configuration. For example, if the site's address is <code>http://example.com</code>, auto-HTTPS will not activate because the scheme is explicitly <code>http://</code>.
+
+[Automatic HTTPS](/docs/automatic-https) is enabled if your site's address contains a hostname or IP address. This behavior is purely implicit, however, so it never overrides any explicit configuration. For example, if the site's address is `http://example.com`, auto-HTTPS will not activate because the scheme is explicitly `http://`.
+
 </aside>
 
+
 From the address, Caddy can potentially infer the scheme, host and port of your site. If the address is without a port, the Caddyfile will choose the port matching the scheme if specified, or the default port of 443 will be assumed.
 
-If you specify a hostname, only requests with a matching Host header will be honored. In other words, if the site address is `localhost`, then Caddy will not match requests to `127.0.0.1`.
+If you specify a hostname, only requests with a matching `Host` header will be honored. In other words, if the site address is `localhost`, then Caddy will not match requests to `127.0.0.1`.
 
 Wildcards (`*`) may be used, but only to represent precisely one label of the hostname. For example, `*.example.com` matches `foo.example.com` but not `foo.bar.example.com`, and `*` matches `localhost` but not `example.com`. To catch all hosts, omit the host portion of the address.
 
-If multiple sites share the same definition, you can list all of them together:
+If multiple sites share the same definition, you can list all of them together; notice how the commas indicate the continuation of addresses:
 
 ```caddy
 localhost:8080, example.com, www.example.com
@@ -196,10 +200,10 @@ example.com,
 www.example.com
 ```
 
-Notice how the commas indicate the continuation of addresses.
-
 An address must be unique; you cannot specify the same address more than once.
 
+By default, sites bind on all network interfaces. If you wish to override this, use the [`bind` directive](/docs/caddyfile/directives/bind) or the [`default_bind` global option](/docs/caddyfile/options#default-bind) to do so.
+
 
 
 ## Matchers

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

@@ -4,11 +4,11 @@ title: bind (Caddyfile directive)
 
 # bind
 
-bind overrides the interface to which the server's socket should bind. Normally, the listener binds to the empty (wildcard) interface. However, you may force the listener to bind to another hostname or IP instead. (This directive accepts only a host, not a port.)
+Overrides the interface to which the server's socket should bind. Normally, the listener binds to the empty (wildcard) interface. However, you may force the listener to bind to another hostname or IP instead. (This directive accepts only a host, not a port.)
 
-Note that binding sites inconsistently may result in unintended consequences. For example, if two sites on the same port resolve to 127.0.0.1 and only one of those sites is configured with `bind 127.0.0.1`, then only one site will be accessible since the other will bind to the port without a specific host; the OS will choose the more specific matching socket. (Virtual hosts are not shared across different listeners.)
+Note that binding sites inconsistently may result in unintended consequences. For example, if two sites on the same port resolve to `127.0.0.1` and only one of those sites is configured with `bind 127.0.0.1`, then only one site will be accessible since the other will bind to the port without a specific host; the OS will choose the more specific matching socket. (Virtual hosts are not shared across different listeners.)
 
-bind also accepts an optional network name: `<network>/<host>`.
+`bind` accepts [network addresses](/docs/conventions#network-addresses), but may not include a port.
 
 
 ## Syntax

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,13 +23,25 @@ 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 {
@@ -54,7 +66,7 @@ Reverse proxy to a professional server that is highly qualified for handling HTT
 handle_errors {
 	rewrite * /{err.status_code}
 	reverse_proxy https://http.cat {
-		header_up Host http.cat
+		header_up Host {upstream_hostport}
 	}
 }
 ```
@@ -67,13 +79,22 @@ handle_errors {
 }
 ```
 
-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 `{err.status_code} >= 400 && {err.status_code} < 500`
+	@404-410 expression `{err.status_code} in [404, 410]`
-	respond @4xx "It's a 4xx error!"
+	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"
+	}
 }
 ```

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

@@ -14,9 +14,12 @@ $(function() {
 Enables and configures HTTP request logging (also known as access logs).
 
 <aside class="tip">
-	If you're looking to configure Caddy's runtime logs, you're looking for the <a href="/docs/caddyfile/options#log"><code>log</code> global option</a> instead.
+
+If you're looking to configure Caddy's runtime logs, you're looking for the [`log` global option](/docs/caddyfile/options#log) instead.
+
 </aside>
 
+
 The `log` directive applies to the host/port of the site block it appears in, not any other part of the site address (e.g. path).
 
 - [Syntax](#syntax)
@@ -131,9 +134,12 @@ output net <address> {
 The **format** subdirective lets you customize how logs get encoded (formatted). It appears within a `log` block.
 
 <aside class="tip">
-	<b>A note about Common Log Format (CLF):</b> CLF clashes with modern structured logs. To transform your access logs into the deprecated Common Log Format, please use the <a href="https://github.com/caddyserver/transform-encoder"><code>transform-encoder</code> plugin</a>.
+
+**A note about Common Log Format (CLF):** CLF clashes with modern structured logs. To transform your access logs into the deprecated Common Log Format, please use the [`transform-encoder` plugin](https://github.com/caddyserver/transform-encoder).
+
 </aside>
 
+
 In addition to the syntax for each individual encoder, these common properties can be set on most encoders:
 
 ```caddy-d

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

@@ -516,7 +516,9 @@ transport fastcgi {
 - **write_timeout** <span id="write_timeout"/> is how long to wait when sending to the FastCGI server. Accepts [duration values](/docs/conventions#durations). Default: no timeout.
 
 <aside class="tip">
-	If you're trying to serve a modern PHP application, you may be looking for the <a href="/docs/caddyfile/directives/php_fastcgi"><code>php_fastcgi</code> directive</a>, which is a shortcut for a proxy using the `fastcgi` directive, with the necessary rewrites for using `index.php` as the routing entrypoint.
+
+If you're trying to serve a modern PHP application, you may be looking for the [`php_fastcgi` directive](/docs/caddyfile/directives/php_fastcgi), which is a shortcut for a proxy using the `fastcgi` directive, with the necessary rewrites for using `index.php` as the routing entrypoint.
+
 </aside>
 
 

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

@@ -58,9 +58,12 @@ route {
 ```
 
 <aside class="tip">
-	Another way to do this is to make the two matchers mutually exclusive, but this can quickly become complex if there are more than one or two conditions. With the <code>route</code> directive, the mutual exclusivity of the two handlers is implicit because they are both terminal handlers.
+
+Another way to do this is to make the two matchers mutually exclusive, but this can quickly become complex if there are more than one or two conditions. With the `route` directive, the mutual exclusivity of the two handlers is implicit because they are both terminal handlers.
+
 </aside>
 
+
 And now `file_server` will be chained in before `redir` because the order is taken literally.
 
 ## Similar directives

src/docs/markdown/caddyfile/options.md

@@ -298,9 +298,12 @@ Customizes [HTTP servers](/docs/json/apps/http/servers/) with settings that pote
 Can be specified more than once, with different `listener_address` values, to configure different options per server. For example, `servers :443` will only apply to the server that is bound to the listener address `:443`. Omitting the listener address will apply the options to any remaining server.
 
 <aside class="tip">
-	Use the <a href="/docs/command-line#caddy-adapt"><code>caddy adapt</code></a> command to find the listen address for the servers in your Caddyfile.
+
+Use the [`caddy adapt`](/docs/command-line#caddy-adapt) command to find the listen address for the servers in your Caddyfile.
+
 </aside>
 
+
 For example, to configure different options for the servers on port `:80` and `:443`, you would specify two `servers` blocks:
 
 ```caddy

src/docs/markdown/command-line.md

@@ -337,9 +337,12 @@ Once started, you can use [`caddy stop`](#caddy-stop) or the [`POST /stop`](/doc
 	[--config &lt;path&gt; [--adapter &lt;name&gt;]]</code></pre>
 
 <aside class="tip">
-	Stopping (and restarting) the server is orthogonal to config changes. <b>Do not use the stop command to change configuration in production, unless you want downtime.</b> Use the <a href="#caddy-reload">caddy reload</a> command instead.
+
+Stopping (and restarting) the server is orthogonal to config changes. **Do not use the stop command to change configuration in production, unless you want downtime.** Use the [`caddy reload`](#caddy-reload) command instead.
+
 </aside>
 
+
 Gracefully stops the running Caddy process (other than the process of the stop command) and causes it to exit. It uses the [`POST /stop`](/docs/api#post-stop)  endpoint of the admin API to perform a graceful shutdown.
 
 The address of this request can be customized using the `--address` flag, or from the given `--config`, if the running instance's admin API is not using the default listen address.

src/docs/markdown/conventions.md

@@ -51,7 +51,9 @@ unix//path/to/socket
 ```
 
 <aside class="tip">
-	Caddy network addresses are not URLs. URLs couple the lower and higher layers of the <a href="https://en.wikipedia.org/wiki/OSI_model#Layer_architecture">OSI model</a>, but Caddy often uses network addresses independently of a specific application, so combining them would be problematic. In Caddy, network addresses refer precisely to resources that can be dialed or bound at L3-L5, but URLs combine L3-L7, which is too many. A network address requires a host+port and path to be mutually exclusive, but URLs do not. Network addresses sometimes support port ranges, but URLs do not.
+
+Caddy network addresses are not URLs. URLs couple the lower and higher layers of the [OSI model](https://en.wikipedia.org/wiki/OSI_model#Layer_architecture), but Caddy often uses network addresses independently of a specific application, so combining them would be problematic. In Caddy, network addresses refer precisely to resources that can be dialed or bound at L3-L5, but URLs combine L3-L7, which is too many. A network address requires a host+port and path to be mutually exclusive, but URLs do not. Network addresses sometimes support port ranges, but URLs do not.
+
 </aside>
 
 
@@ -60,9 +62,12 @@ unix//path/to/socket
 Caddy's configuration supports the use of _placeholders_ (variables). Using placeholders is a simple way to inject dynamic values into a static configuration.
 
 <aside class="tip">
-	Placeholders are a similar idea to variables in other software. For example, <a href="https://nginx.org/en/docs/varindex.html">nginx has variables</a> like $uri and $document_root.
+
+Placeholders are a similar idea to variables in other software. For example, [nginx has variables](https://nginx.org/en/docs/varindex.html) like `$uri` and `$document_root`.
+
 </aside>
 
+
 Placeholders are bounded on either side by curly braces `{ }` and contain the variable name inside, for example: `{foo.bar}`. Placeholder braces can be escaped, `\{like so\}`. Variable names are typically namespaced with dots to avoid collisions across modules.
 
 Which placeholders are available depends on the context. Not all placeholders are available in all parts of the config. For example, [the HTTP app sets placeholders](/docs/json/apps/http/#docs) that are only available in areas of the config related to handling HTTP requests.
@@ -94,10 +99,13 @@ This section contains information about where to find various files. File and di
 There is no single, conventional place for you to put your config files. Put them wherever makes the most sense to you.
 
 <aside class="tip">
-	The only exception to this might be a file named "Caddyfile" in the current working directory, which the caddy command tries for convenience if no other config file is specified.
+
+The only exception to this might be a file named `Caddyfile` in the current working directory, which the caddy command tries for convenience if no other config file is specified.
+
 </aside>
 
-Distributions that ship with a default config file should document where this config file is at, even if it might be obvious to the package/distro maintainers.
+
+Distributions that ship with a default config file should document where this config file is at, even if it might be obvious to the package/distro maintainers. For most Linux installations, the Caddyfile will be found at `/etc/caddy/Caddyfile`.
 
 
 ### Data directory
@@ -128,9 +136,12 @@ It is crucial that this directory is persistent and writeable by Caddy.
 This is where Caddy may store certain configuration to disk. Most notably, it persists the last active configuration (by default) to this folder for easy resumption later using [`caddy run --resume`](/docs/command-line#caddy-run).
 
 <aside class="tip">
-	The configuration directory is <i>not</i> where you need to store <a href="#your-config-files">your config files</a>. (Though, you are allowed to.)
+
+The configuration directory is *not* where you need to store [your config files](#your-config-files). (Though, you are allowed to.)
+
 </aside>
 
+
 If the `XDG_CONFIG_HOME` environment variable is set, it is `$XDG_CONFIG_HOME/caddy`.
 
 Otherwise, its path varies by platform, adhering to OS conventions:
@@ -150,7 +161,7 @@ It is crucial that this directory is persistent and writeable by Caddy.
 
 ## Durations
 
-Duration strings are commonly used throughout Caddy's configuration. They take on the same format as [Go's time.ParseDuration syntax](https://golang.org/pkg/time/#ParseDuration) except you can also use `d` for day (we assume 1 day = 24 hours for simplicity). Valid units are:
+Duration strings are commonly used throughout Caddy's configuration. They take on the same format as [Go's `time.ParseDuration` syntax](https://golang.org/pkg/time/#ParseDuration) except you can also use `d` for day (we assume 1 day = 24 hours for simplicity). Valid units are:
 
 - `ns` (nanosecond)
 - `us`/`µs` (microsecond)

src/docs/markdown/extending-caddy.md

@@ -49,9 +49,12 @@ foo.gizmo
 ...</code></pre>
 
 <aside class="tip">
-	The <a href="https://github.com/caddyserver/xcaddy"><code>xcaddy</code> command</a> is an important part of every module developer's workflow. It compiles Caddy with your plugin, then runs it with the given arguments. It discards the temporary binary each time (similar to <code>go run</code>).
+
+The [`xcaddy` command](https://github.com/caddyserver/xcaddy) is an important part of every module developer's workflow. It compiles Caddy with your plugin, then runs it with the given arguments. It discards the temporary binary each time (similar to `go run`).
+
 </aside>
 
+
 Congratulations, your module registers with Caddy and can be used in [Caddy's config document](/docs/json/) in whatever places use modules in the same namespace.
 
 Under the hood, `xcaddy` is simply making a new Go module that requires both Caddy and your plugin (with an appropriate `replace` to use your local development version), then adds an import to ensure it is compiled in:

src/docs/markdown/getting-started.md

@@ -45,9 +45,12 @@ This blocks forever, but what is it doing? At the moment... nothing. By default,
 <pre><code class="cmd bash">curl localhost:2019/config/</code></pre>
 
 <aside class="tip">
-	This is <b>not</b> your website: the administration endpoint at localhost:2019 is used for controlling Caddy and is restricted to localhost by default.
+
+This is **not** your website: the administration endpoint at localhost:2019 is used for controlling Caddy and is restricted to localhost by default.
+
 </aside>
 
+
 <aside class="complete">Try the API</aside>
 
 We can make Caddy useful by giving it a config. This can be done many ways, but we'll start by making a POST request to the [/load](/docs/api#post-load) endpoint using `curl` in the next section.
@@ -83,9 +86,12 @@ Save this to a JSON file (e.g. `caddy.json`):
 ```
 
 <aside class="tip">
-	You do not have to use config files, but we are for this tutorial. Caddy's <a href="/docs/api">admin API</a> is designed for use by other programs or scripts.
+
+You do not have to use config files, but we are for this tutorial. Caddy's [admin API](/docs/api) is designed for use by other programs or scripts.
+
 </aside>
 
+
 Then upload it:
 
 <pre><code class="cmd bash">curl localhost:2019/load \
@@ -195,9 +201,12 @@ It is important to note that both JSON and the Caddyfile (and [any other support
 ## API vs. Config files
 
 <aside class="tip">
-	Under the hood, even config files go through Caddy's API endpoints; the <code>caddy</code> command just wraps up those API calls for you.
+
+Under the hood, even config files go through Caddy's API endpoints; the `caddy` command just wraps up those API calls for you.
+
 </aside>
 
+
 You will also want to decide whether your workflow is API-based or CLI-based. (You _can_ use both the API and config files on the same server, but we don't recommend it: best to have one source of truth.)
 
 API | Config files

src/docs/markdown/install.md

@@ -16,7 +16,9 @@ This page describes various methods for installing Caddy on your system.
 - [DigitalOcean](#digitalocean)
 
 <aside class="tip">
-    Our <a href="https://github.com/caddyserver/dist">official packages</a> come only with the standard modules. If you need third-party plugins, <a href="/docs/build#xcaddy">build from source with <code>xcaddy</code></a> or use <a href="/download">our download page</a>.
+
+Our [official packages](https://github.com/caddyserver/dist) come only with the standard modules. If you need third-party plugins, [build from source with `xcaddy`](/docs/build#xcaddy) or use [our download page](/download).
+
 </aside>
 
 

src/docs/markdown/logging.md

@@ -131,9 +131,12 @@ As you saw above, messages are emitted by **loggers**. The messages are then sen
 Caddy lets you [configure multiple logs](/docs/json/logging/logs/) which can process messages. A log consists of an encoder, writer, minimum level, sampling ratio, and a list of loggers to include or exclude. In Caddy, there is always a default log named `default`. You can customize it by specifying a log keyed as `"default"` in [this object](/docs/json/logging/logs/) in the config.
 
 <aside class="tip">
-	Now would be a good time to <a href="/docs/json/logging/">explore Caddy's logging docs</a> so you can become familiar with the structure and parameters we're talking about.
+
+Now would be a good time to [explore Caddy's logging docs](/docs/json/logging/) so you can become familiar with the structure and parameters we're talking about.
+
 </aside>
 
+
 - **Encoder:** The format for the log. Transforms the in-memory data representation into a byte slice. Encoders have access to all fields of a log message.
 - **Writer:** The log output. Can be any log writer module, like to a file or network socket. It simply writes bytes.
 - **Level:** Logs have various levels, from DEBUG to FATAL. Messages lower than the specified level will be ignored by the log.

src/docs/markdown/metrics.md

@@ -135,9 +135,9 @@ All Caddy HTTP middleware handlers are instrumented automatically for
 determining request latency, time-to-first-byte, errors, and request/response
 body sizes.
 
-<aside class="tip">Because all middleware handlers are instrumented, and many
+<aside class="tip">
-requests are handled by multiple handlers, make sure not to simply sum
+	Because all middleware handlers are instrumented, and many requests are handled by multiple handlers, make sure not to simply sum all the counters together.
-all the counters together.</aside>
+</aside>
 
 For the histogram metrics below, the buckets are currently not configurable.
 For durations, the default ([`prometheus.DefBuckets`](https://pkg.go.dev/github.com/prometheus/client_golang/prometheus#pkg-variables)
@@ -220,9 +220,12 @@ Label  | Description
 Once you have Prometheus scraping Caddy's metrics, you can start to see some
 interesting metrics about how Caddy's performing.
 
-<aside class="tip">If you've started up a Prometheus server to scrape Caddy with
+<aside class="tip">
-the config above, try pasting these queries into the Prometheus UI at
+
-<a href="http://localhost:9090/graph">http://localhost:9090/graph</a></aside>
+If you've started up a Prometheus server to scrape Caddy with the config above, try pasting these queries into the Prometheus UI at [http://localhost:9090/graph](http://localhost:9090/graph)
+
+</aside>
+
 
 For example, to see the per-second request rate, as averaged over 5 minutes:
 

src/docs/markdown/quick-starts/caddyfile.md

@@ -13,9 +13,12 @@ localhost
 ```
 
 <aside class="tip">
-	If the HTTP and HTTPS ports (80 and 443, respectively) are privileged ports on your OS, you will either need to run with elevated privileges or use a higher port. To use a higher port, just change the address to something like <code>localhost:2015</code> and change the HTTP port using the <a href="/docs/caddyfile/options">http_port</a> Caddyfile option.
+
+If the HTTP and HTTPS ports (80 and 443, respectively) are privileged ports on your OS, you will either need to run with elevated privileges or use a higher port. To use a higher port, just change the address to something like `localhost:2015` and change the HTTP port using the [`http_port`](/docs/caddyfile/options) Caddyfile option.
+
 </aside>
 
+
 Then hit enter and type what you want it to do, so it looks like this:
 
 ```caddy

src/docs/markdown/quick-starts/https.md

@@ -30,7 +30,9 @@ Before continuing, verify correct records with an authoritative lookup. Replace
 
 Also make sure your server is externally reachable on ports 80 and 443 from a public interface.
 
-<aside class="tip">If you're on your home or other restricted network, you may need to forward ports or adjust firewall settings.</aside>
+<aside class="tip">
+	If you're on your home or other restricted network, you may need to forward ports or adjust firewall settings.
+</aside>
 
 All we have to do is start Caddy with your domain name in the config. There are several ways to do this.