From 98af4363d1f13d966618699257bc7628c12d8102 Mon Sep 17 00:00:00 2001
From: Francis Lavoie <lavofr@gmail.com>
Date: Wed, 17 Feb 2021 19:43:32 -0500
Subject: [PATCH] docs: Revise the `handle` cross-linking, add another example

---
 .../markdown/caddyfile/directives/handle.md   | 24 +++++++++++++++----
 .../markdown/caddyfile/directives/route.md    |  7 ++++++
 2 files changed, 27 insertions(+), 4 deletions(-)

diff --git a/src/docs/markdown/caddyfile/directives/handle.md b/src/docs/markdown/caddyfile/directives/handle.md
index 9b2d38b..2430304 100644
--- a/src/docs/markdown/caddyfile/directives/handle.md
+++ b/src/docs/markdown/caddyfile/directives/handle.md
@@ -8,10 +8,6 @@ Evaluates a group of directives mutually exclusively from other `handle` blocks
 
 The `handle` directive is kind of similar to the `location` directive from nginx config: the first matching `handle` block will be evaluated. Handle blocks can be nested if needed. Only HTTP handler directives can be used inside handle blocks.
 
-<aside class="tip">
-	See also the [`handle_path`](/docs/caddyfile/directives/handle_path) directive if you need to strip the matched path prefix.
-</aside>
-
 ## Syntax
 
 ```caddy-d
@@ -27,6 +23,14 @@ handle [<matcher>] {
 
 If you prefer crafting HTTP handler logic in a more inheritence-based way like nginx location blocks, you may prefer the use of `handle` blocks rather than defining mutually-exclusive matchers for your directives. If inheritence 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 other HTTP handler directives, but but imply a different intent or behave subtly differently:
+
+- [`handle_path`](handle_path) does the same as `handle`, but also has built-in path prefix stripping logic built-in before handling the directives within.
+- [`handle_errors`](handle_errors), similarly to `handle`, wraps other directives, but is instead invoked when Caddy encounters an error during request handling.
+- [`route`](route) similarly to `handle`, wraps other directives, but instead of providing mutual exclusivity, allows overriding the default [directive order](/docs/caddyfile/directives#directive-order).
+
 ## Examples
 
 Handle requests in `/foo/` by the static file server, and send all other requests to the reverse proxy:
@@ -39,3 +43,15 @@ 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 eachother:
+
+```caddy-d
+handle_path /foo/* {
+	# The path has the "/foo" prefix stripped
+}
+
+handle /bar/* {
+	# The path still retains "/bar"
+}
+```
diff --git a/src/docs/markdown/caddyfile/directives/route.md b/src/docs/markdown/caddyfile/directives/route.md
index f5fe6a0..a0c90d2 100644
--- a/src/docs/markdown/caddyfile/directives/route.md
+++ b/src/docs/markdown/caddyfile/directives/route.md
@@ -63,6 +63,13 @@ route {
 
 And now `file_server` will be chained in before `redir` because the order is taken literally.
 
+## Similar directives
+
+There are other directives that can wrap other HTTP handler directives, but but imply a different intent or behave subtly differently:
+
+- [`handle`](route) similarly to `route`, wraps other directives, but instead overriding the default directive order, provides mutual exclusivity with other `handle` blocks.
+- [`handle_path`](handle_path) does the same as `handle`, but also has built-in path prefix stripping logic built-in before handling the directives within.
+- [`handle_errors`](handle_errors), similarly to `route`, wraps other directives, but is instead invoked when Caddy encounters an error during request handling.
 
 ## Examples