diff --git a/src/docs/markdown/caddyfile/directives/reverse_proxy.md b/src/docs/markdown/caddyfile/directives/reverse_proxy.md
index 57f7ce4..b746f78 100644
--- a/src/docs/markdown/caddyfile/directives/reverse_proxy.md
+++ b/src/docs/markdown/caddyfile/directives/reverse_proxy.md
@@ -139,6 +139,7 @@ Static upstream addresses can take the form of a URL that contains only scheme a
 
 - `localhost:4000`
 - `127.0.0.1:4000`
+- `[::1]:4000`
 - `http://localhost:4000`
 - `https://example.com`
 - `h2c://127.0.0.1`
@@ -146,6 +147,7 @@ Static upstream addresses can take the form of a URL that contains only scheme a
 - `unix//var/php.sock`
 - `unix+h2c//var/grpc.sock`
 - `localhost:8001-8006`
+- `[fe80::ea9f:80ff:fe46:cbfd%eth0]:443`
 
 By default, connections are made to the upstream over plaintext HTTP. When using the URL form, a scheme can be used to set some [`transport`](#transports) defaults as a shorthand.
 - Using `https://` as the scheme will use the [`http` transport](#the-http-transport) with [`tls`](#tls) enabled.
@@ -158,6 +160,8 @@ By default, connections are made to the upstream over plaintext HTTP. When using
 
 Schemes cannot be mixed, since they modify the common transport configuration (a TLS-enabled transport cannot carry both HTTPS and plaintext HTTP). Any explicit transport configuration will not be overwritten, and omitting schemes or using other ports will not assume a particular transport.
 
+When using IPv6 with a zone (e.g. link-local addresses with a specific network interface), a scheme **cannot** be used as a shortcut because the `%` will result in a URL-parse error; configure the transport explicitly instead.
+
 When using the [network address](/docs/conventions#network-addresses) form, the network type is specified as a prefix to the upstream address. This cannot be combined with a URL scheme. As a special case, `unix+h2c/` is supported as a shortcut for the `unix/` network plus the same effects as the `h2c://` scheme. Port ranges are supported as a shortcut, which expands to multiple upstreams with the same host.
 
 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.
diff --git a/src/docs/markdown/conventions.md b/src/docs/markdown/conventions.md
index 2b4b932..0542ae7 100644
--- a/src/docs/markdown/conventions.md
+++ b/src/docs/markdown/conventions.md
@@ -38,11 +38,14 @@ The address part may be any of these forms:
 - `host`
 - `host:port`
 - `:port`
+- `[ipv6%zone]:port`
 - `/path/to/unix/socket`
 - `/path/to/unix/socket|0200`
 
 The host may be any hostname, resolvable domain name, or IP address.
 
+In the case of IPv6 addresses, the address must be enclosed in square brackets `[]`. The zone identifier (starting with `%`) is optional (often used for link-local addresses).
+
 The port may be a single value (`:8080`) or an inclusive range (`:8080-8085`). A port range will be multiplied into singular addresses. Not all config fields accept port ranges. The special port `:0` means any available port.
 
 A unix socket path is only acceptable when using a `unix*` network type. The forward slash that separates the network and address is not considered part of the path.
@@ -59,6 +62,8 @@ localhost:8080-8085
 tcp/localhost:8080
 tcp/localhost:8080-8085
 udp/localhost:9005
+[::1]:8080
+tcp6/[fe80::1%eth0]:8080
 unix//path/to/socket
 unix//path/to/socket|0200
 ```