From 9d7e9c398e2973aa099b60626d977d30a21f8b01 Mon Sep 17 00:00:00 2001
From: Dean Chen <862469039@qq.com>
Date: Mon, 10 Aug 2026 13:46:57 +0500
Subject: [PATCH] docs: show custom intermediate CA without online root key

Document how to load a pem_file intermediate for signing while only
shipping the root cert, pick a non-local CA id, and wire tls issuer
internal to that CA.

Signed-off-by: Dean Chen <862469039@qq.com>
---
 src/docs/markdown/caddyfile/options.md | 38 ++++++++++++++++++++++++++
 1 file changed, 38 insertions(+)

diff --git a/src/docs/markdown/caddyfile/options.md b/src/docs/markdown/caddyfile/options.md
index e8f9e9d7..2411a0ac 100644
--- a/src/docs/markdown/caddyfile/options.md
+++ b/src/docs/markdown/caddyfile/options.md
@@ -1429,6 +1429,44 @@ A key pair (certificate and private key) to use as the intermediate for the CA.
 }
 ```
 
+To sign site certificates with a **custom intermediate** while keeping the root
+private key offline, load the intermediate cert/key as usual and only supply the
+root **certificate** for chain building. The Caddyfile still expects a `key`
+path under `root`; when the root key is not available, point it at any PEM file
+Caddy can read (operators often reuse the intermediate key path as a stand-in).
+Caddy does not use that root key for signing when an intermediate key pair is
+configured.
+
+Prefer a non-default CA id (not `local`) and select it from the site block so
+you do not clash with the auto-managed local CA:
+
+```caddy
+{
+	pki {
+		ca company {
+			root {
+				format pem_file
+				cert /var/certs/root-ca.crt
+				key /var/certs/sub-ca.key
+			}
+			intermediate {
+				format pem_file
+				cert /var/certs/sub-ca.crt
+				key /var/certs/sub-ca.key
+			}
+		}
+	}
+}
+
+my.example {
+	tls {
+		issuer internal {
+			ca company
+		}
+	}
+}
+```
+
 
 ## Event Options