From 41470c4e026c121bce6adb9ce414af6fecefd727 Mon Sep 17 00:00:00 2001
From: a <edward9.lee@gmail.com>
Date: Wed, 19 Jun 2024 16:07:03 -0500
Subject: [PATCH] caddyfile: snippet block input documentation (#400)

* initial

* Update Caddyfile

* tabs

* add note to other page
---
 src/docs/markdown/caddyfile/concepts.md       | 23 ++++++++
 .../markdown/caddyfile/directives/import.md   | 52 ++++++++++++++++++-
 2 files changed, 74 insertions(+), 1 deletion(-)

diff --git a/src/docs/markdown/caddyfile/concepts.md b/src/docs/markdown/caddyfile/concepts.md
index e3fbf92..69554a6 100644
--- a/src/docs/markdown/caddyfile/concepts.md
+++ b/src/docs/markdown/caddyfile/concepts.md
@@ -413,6 +413,29 @@ b.example.com {
 }
 ```
 
+⚠️ <i>Experimental</i> <span style='white-space: pre;'> | </span> <span>v2.9.x+</span>
+
+You can also pass an optional block to an imported snippet, and use them as follows.
+
+```caddy
+(snippet) {
+	{block}
+	respond "OK"
+}
+
+a.example.com {
+	import snippet {
+		header +foo bar
+	}
+}
+
+b.example.com {
+	import snippet {
+		header +bar foo
+	}
+}
+```
+
 **[Read the `import` directive page](/docs/caddyfile/directives/import) to learn more.**
 
 
diff --git a/src/docs/markdown/caddyfile/directives/import.md b/src/docs/markdown/caddyfile/directives/import.md
index bc7a248..dc74764 100644
--- a/src/docs/markdown/caddyfile/directives/import.md
+++ b/src/docs/markdown/caddyfile/directives/import.md
@@ -11,7 +11,7 @@ This directive is a special case: it is evaluated before the structure is parsed
 ## Syntax
 
 ```caddy-d
-import <pattern> [<args...>]
+import <pattern> [<args...>] [{block}]
 ```
 
 - **&lt;pattern&gt;** is the filename, glob pattern, or name of [snippet](/docs/caddyfile/concepts#snippets) to include. Its contents will replace this line as if that file's contents appeared here to begin with.
@@ -34,6 +34,11 @@ import <pattern> [<args...>]
 
   Note that prior to v2.7.0, the syntax was `{args.N}` but this form was deprecated in favor of the more flexible syntax above.
 
+⚠️ <i>Experimental</i> <span style='white-space: pre;'> | </span> <span>v2.9.x+</span>
+- **{block...}** is an optional block to pass to the imported tokens. This placeholder is a special case, and is evaluated recursively at Caddyfile-parse-time, not at runtime. They can be used in two forms:
+  - `{block}` where the content of provided block will be substituted for the placeholder.
+  - `{block.key}` where `key` is the first token of a parameter within the provided block
+
 
 ## Examples
 
@@ -85,3 +90,48 @@ example.com {
 	import proxy-rewrite /api 10.0.0.1 10.0.0.2 10.0.0.3
 }
 ```
+
+
+⚠️ <i>Experimental</i> <span style='white-space: pre;'> | </span> <span>v2.9.x+</span>
+
+Import a snippet which provides extendable options for a reverse proxy
+
+```caddy
+(extendable-proxy) {
+	reverse_proxy {
+		to {block.proxy_target}
+		{block.proxy_options}
+	}
+}
+
+example.com {
+	import extendable-proxy {
+	  proxy_target 10.0.0.1
+	  proxy_options {
+		transport http {
+			tls
+		}
+	  }
+	}
+}
+```
+
+Import a snippet that serves any set of directives, but with a pre-loaded middleware.
+
+```caddy
+(instrumented-route) {
+	header {
+	  Alt-Svc `h3="0.0.0.0:443"; ma=2592000`
+	}
+	tracing {
+		span args[0]
+	}
+	{block}
+}
+
+example.com {
+	import instrumented-route example-com {
+		respond "OK"
+	}
+}
+```