From d798a9e432a202775cc75ca4333e24a2e3576279 Mon Sep 17 00:00:00 2001
From: Francis Lavoie <lavofr@gmail.com>
Date: Fri, 6 Oct 2023 01:49:45 -0400
Subject: [PATCH] Improve matcher syntax docs, augment handle_path docs

---
 .../caddyfile/directives/handle_path.md       | 22 ++++++++++++++++---
 src/docs/markdown/caddyfile/matchers.md       | 10 +++++----
 2 files changed, 25 insertions(+), 7 deletions(-)

diff --git a/src/docs/markdown/caddyfile/directives/handle_path.md b/src/docs/markdown/caddyfile/directives/handle_path.md
index 8812cabf..30060539 100644
--- a/src/docs/markdown/caddyfile/directives/handle_path.md
+++ b/src/docs/markdown/caddyfile/directives/handle_path.md
@@ -2,9 +2,25 @@
 title: handle_path (Caddyfile directive)
 ---
 
+<script>
+window.$(function() {
+	// Add a link to [<path_matcher>] as a special case for this directive.
+	// The matcher text includes <> characters which are parsed as HTML,
+	// so we must use text() to change the link text.
+	window.$('pre.chroma .s:contains("<path_matcher>")')
+		.map(function(k, item) {
+			let text = item.innerText.replace(/</g, '&lt;').replace(/>/g, '&gt;');
+			window.$(item)
+				.html('<a href="/docs/caddyfile/matchers#path-matchers" style="color: inherit;" title="Matcher token">' + text + '</a>')
+				.removeClass('s')
+				.addClass('nd');
+		});
+});
+</script>
+
 # handle_path
 
-Same as the [`handle` directive](/docs/caddyfile/directives/handle), but implicitly strips the matched path prefix.
+Works the same as the [`handle` directive](/docs/caddyfile/directives/handle), but implicitly uses [`uri strip_prefix`](/docs/caddyfile/directives/uri) to strip the matched path prefix.
 
 Handling a request matching a certain path (while stripping that path from the request URI) is a common enough use case that it has its own directive for convenience.
 
@@ -17,9 +33,9 @@ handle_path <path_matcher> {
 }
 ```
 
-- **<directives...>** is a list of HTTP handler directives or directive blocks, one per line, just like would be used outside of a handle_path block.
+- **<directives...>** is a list of HTTP handler directives or directive blocks, one per line, just like would be used outside of a `handle_path` block.
 
-Note that only a single path matcher is accepted and required; you cannot use other kinds of matchers with handle_path.
+Only a single [path matcher](/docs/caddyfile/matchers#path-matchers) is accepted, and is required; you cannot use named matchers with `handle_path`.
 
 ## Examples
 
diff --git a/src/docs/markdown/caddyfile/matchers.md b/src/docs/markdown/caddyfile/matchers.md
index 45322988..9eb97b6d 100644
--- a/src/docs/markdown/caddyfile/matchers.md
+++ b/src/docs/markdown/caddyfile/matchers.md
@@ -58,11 +58,11 @@ window.$(function() {
 
 In the Caddyfile, a **matcher token** immediately following the directive can limit that directive's scope. The matcher token can be one of these forms:
 
-1. **`*`** to match all requests (wildcard; default).
-2. **`/path`** start with a forward slash to match a request path.
-3. **`@name`** to specify a _named matcher_.
+1. [**`*`**](#wildcard-matchers) to match all requests (wildcard; default).
+2. [**`/path`**](#path-matchers) start with a forward slash to match a request path.
+3. [**`@name`**](#named-matchers) to specify a _named matcher_.
 
-Matcher tokens are [usually optional](/docs/caddyfile/directives#matchers). If a matcher token is omitted, it is the same as a wildcard matcher (`*`).
+If a directive supports matchers, it will appear as `[<matcher>]` in its syntax documentation. Matcher tokens are [usually optional](/docs/caddyfile/directives#syntax), denoted by `[ ]`. If the matcher token is omitted, it is the same as a wildcard matcher (`*`).
 
 
 #### Examples
@@ -173,6 +173,8 @@ A named matcher definition constitutes a _matcher set_. Matchers in a set are AN
 
 Multiple matchers of the same type may be unioned (e.g. multiple `path` matchers in the same set) using boolean algebra (AND/OR), as described in their respective sections below.
 
+For more complex boolean matching logic, it's recommended to the [`expression` matcher](#expression) to write a CEL expression, which supports _and_ `&&`, _or_ `||`, and _parentheses_ `( )`.
+