Big Caddyfile docs update (#374)

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

@@ -6,7 +6,11 @@ title: handle (Caddyfile directive)
 
 Evaluates a group of directives mutually exclusively from other `handle` blocks at the same level of nesting.
 
-The `handle` directive is kind of similar to the `location` directive from nginx config: the first matching `handle` block will be evaluated. `handle` directives at the same level of nesting will be tried in the order they're written in the `Caddyfile`, except if there is a single path matcher, which orders them by longest (most specific) path pattern first. Handle blocks can be nested if needed. Only HTTP handler directives can be used inside handle blocks.
+In other words, when multiple `handle` directives appear in sequence, only the first _matching_ `handle` block will be evaluated. A handle with no matcher acts like a _fallback_ route.
+
+The `handle` directives are sorted according to the [directive sorting algorithm](/docs/caddyfile/directives#sorting-algorithm) by their matchers. The [`handle_path`](handle_path) directive is a special case which sorts at the same priority as a `handle` with a path matcher.
+
+Handle blocks can be nested if needed. Only HTTP handler directives can be used inside handle blocks.
 
 ## Syntax
 
@@ -19,39 +23,67 @@ handle [<matcher>] {
 - **<directives...>** is a list of HTTP handler directives or directive blocks, one per line, just like would be used outside of a handle block.
 
 
-## Utility
-
-If you prefer crafting HTTP handler logic in a more inheritance-based way like nginx location blocks, you may prefer the use of `handle` blocks rather than defining mutually-exclusive matchers for your directives. If inheritance is a desired characteristic of your HTTP handler configurations, then the `handle` directive may suit you well.
 
 ## Similar directives
 
 There are other directives that can wrap HTTP handler directives, but each has its use depending on the behavior you want to convey:
 
 - [`handle_path`](handle_path) does the same as `handle`, but it strips a prefix from the request before running its handlers.
+
 - [`handle_errors`](handle_errors) is like `handle`, but is only invoked when Caddy encounters an error during request handling.
-- [`route`](route) wraps other directives like `handle` does, but with two distinctions: 1) route blocks are not mutually exclusive to each other, and 2) directives within a route are not [re-ordered](/docs/caddyfile/directives#directive-order), giving you more control if needed.
+
+- [`route`](route) wraps other directives like `handle` does, but with two distinctions:
+  1. route blocks are not mutually exclusive to each other,
+  2. directives within a route are not [re-ordered](/docs/caddyfile/directives#directive-order), giving you more control if needed.
+
+
 
 ## Examples
 
-Handle requests in `/foo/` by the static file server, and send all other requests to the reverse proxy:
+Handle requests in `/foo/` with the static file server, and other requests with the reverse proxy:
 
-```caddy-d
-handle /foo/* {
-	file_server
-}
-handle {
-	reverse_proxy 127.0.0.1:8080
+```caddy
+example.com {
+	handle /foo/* {
+		file_server
+	}
+
+	handle {
+		reverse_proxy 127.0.0.1:8080
+	}
 }
 ```
 
-You can mix `handle` and [`handle_path`](handle_path) directives in the same site, and they will still be mutually exclusive from each other:
+You can mix `handle` and [`handle_path`](handle_path) in the same site, and they will still be mutually exclusive from each other:
 
-```caddy-d
-handle_path /foo/* {
-	# The path has the "/foo" prefix stripped
-}
+```caddy
+example.com {
+	handle_path /foo/* {
+		# The path has the "/foo" prefix stripped
+	}
 
-handle /bar/* {
-	# The path still retains "/bar"
+	handle /bar/* {
+		# The path still retains "/bar"
+	}
+}
+```
+
+You can nest `handle` blocks to create more complex routing logic:
+
+```caddy
+example.com {
+	handle /foo* {
+		handle /foo/bar* {
+			# This block only matches paths under /foo/bar
+		}
+
+		handle {
+			# This block matches everything else under /foo/
+		}
+	}
+
+	handle {
+		# This block matches everything else (acts as a fallback)
+	}
 }
 ```