link directives to response matchers documentation

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

@@ -29,10 +29,7 @@ encode [<matcher>] <formats...> {
 	
 	minimum_length <length>
 
-	match {
+	match <inline_response_matcher>
-		status <code...>
-		header <field> [<value>]
-	}
 }
 ```
 

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

@@ -38,14 +38,7 @@ header [<matcher>] [[+|-|?|>]<field> [<value>|<find>] [<replace>]] {
 
 	[defer]
 
-	# a match condition
+	match <inline_response_matcher>
-	match [status <code...> | header <field> <value>]
-
-	# or a match block
-	match {
-		status <code...>
-		header <field> [<value>]
-	}
 }
 ```
 

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

@@ -18,10 +18,6 @@ window.$(function() {
 	window.$('pre.chroma .nd:contains("@name")').first().slice(0, 3)
 		.wrapAll('<span class="nd">').parent()
 		.html('<a href="/docs/caddyfile/response-matchers" style="color: inherit;">@name</a>')
-	window.$('pre.chroma .k:contains("replace_status")').first().next()
-		.html('<a href="/docs/caddyfile/response-matchers" style="color: inherit;" title="Response matcher">[&lt;matcher&gt;]</a>')
-	window.$('pre.chroma .k:contains("handle_response")').first().next()
-		.html('<a href="/docs/caddyfile/response-matchers" style="color: inherit;" title="Response matcher">[&lt;matcher&gt;]</a>')
 	window.$('pre.chroma .k')
 		.filter((i, el) => el.innerText === 'status')
 		.html('<a href="/docs/caddyfile/response-matchers#status" style="color: inherit;">status</a>')
@@ -49,19 +45,19 @@ intercept [<matcher>] {
 		header <field> [<value>]
 	}
 
-	replace_status [<matcher>] <code>
+	replace_status [<response_matcher>] <code>
 
-	handle_response [<matcher>] {
+	handle_response [<response_matcher>] {
 		<directives...>
 	}
 }
 ```
 
-- **@name** is the name of a [response matcher](/docs/caddyfile/response-matchers). As long as each response matcher has a unique name, multiple matchers can be defined. A response can be matched on the status code and presence or value of a response header.
+- **@name** is a named [response matcher](/docs/caddyfile/response-matchers) block. As long as each response matcher has a unique name, multiple matchers can be defined. A response can be matched on the status code and presence or value of a response header.
 
 - **replace_status** <span id="replace_status"/> simply changes the status code of response when matched by the given matcher.
 
-- **handle_response** <span id="handle_response"/> defines the route to execute when matched by the given matcher (or, if a matcher is omitted, all responses). The first matching block will be applied. Inside a `handle_response` block, any other [directives](/docs/caddyfile/directives) can be used.
+- **handle_response** <span id="handle_response"/> defines the route to execute when the original response is matched by the given response matcher. If a matcher is omitted, all responses are intercepted. When multiple `handle_response` blocks are defined, the first matching block will be applied. Inside the block, all other [directives](/docs/caddyfile/directives) can be used.
 
 Within `handle_response` routes, the following placeholders are available to pull information from the original response:
 

src/docs/markdown/caddyfile/response-matchers.md

@@ -35,14 +35,39 @@ These typically only appear as config inside of certain other directives, to mak
 
 ## Syntax
 
+If a directive accepts response matchers, the usage is represented as either [<response_matcher>] or [<inline_response_matcher>] in the syntax documentation.
+
+- The **<response_matcher>** token can be the name of a previously declared named response matcher. For example: `@name`.
+- The **<inline_response_matcher>** token can be the response criteria itself, without requiring prior declaration. For example: `status 200`.
+
+### Named
+
 ```caddy-d
 @name {
 	status <code...>
 	header <field> [<value>]
 }
 ```
+If only one aspect of the response is relevant to the directive, you can put the name and the criteria on the same line:
 
+```caddy-d
+@name status <code...>
+```
 
+### Inline
+
+```caddy-d
+{
+	status <code...>
+	header <field> [<value>]
+}
+```
+```caddy-d
+status <code...>
+```
+```caddy-d
+header <field> [<value>]
+```
 
 ## Matchers
 

src/old/resources/js/docs.js

@@ -55,6 +55,19 @@ $(function() {
 			let text = item.innerText.replace(/</g,'&lt;').replace(/>/g,'&gt;');
 			$(item).html('<a href="/docs/caddyfile/matchers#syntax" style="color: inherit;" title="Matcher token">' + text + '</a>');
 		});
+	// Add links to [<matcher>] or named matcher tokens in code blocks.
+	// The matcher text includes <> characters which are parsed as HTML,
+	// so we must use text() to change the link text.
+	$('pre.chroma .s:contains("<response_matcher>")')
+		.add('pre.chroma .s:contains("<inline_response_matcher>")')
+		.map(function(k, /** @type { HTMLElement } */ item) {
+			const anchor = document.createElement("a");
+			anchor.href = "/docs/caddyfile/response-matchers#syntax";
+			anchor.style.color = "inherit";
+			anchor.title = "Response matcher token";
+			item.replaceWith(anchor);
+			anchor.appendChild(item);
+		});
 
 	// Wrap all tables in a div so we can apply overflow-x: scroll
 	$('table').wrap('<div class="table-wrapper"></div>');