docs: Add error caddyfile directive (#143)

Docs for the new directive in caddyserver/caddy#4034.

Also adding a bit in `handle_errors` mentioning that `reverse_proxy` doesn't trigger errors when a response has an "error" HTTP status; not sure how to word this clearly, cause `reverse_proxy` still can trigger errors if there's no upstream or whatever. We should probably add examples for that later, and augment this paragraph to mention `handle_response` once that's merged (caddyserver/caddy#4021)

src/docs/markdown/caddyfile/directives.md

@@ -13,6 +13,7 @@ Directive | Description
 **[basicauth](/docs/caddyfile/directives/basicauth)** | Enforces HTTP Basic Authentication
 **[bind](/docs/caddyfile/directives/bind)** | Customize the server's socket address
 **[encode](/docs/caddyfile/directives/encode)** | Encodes (usually compresses) responses
+**[error](/docs/caddyfile/directives/error)** | Trigger an error
 **[file_server](/docs/caddyfile/directives/file_server)** | Serve files from disk
 **[handle](/docs/caddyfile/directives/handle)** | A mutually-exclusive group of directives
 **[handle_errors](/docs/caddyfile/directives/handle_errors)** | Defines routes for handling errors
@@ -104,6 +105,7 @@ php_fastcgi
 file_server
 acme_server
 abort
+error
 ```
 
 You can override/customize this ordering by using the [`order` global option](/docs/caddyfile/options) or the [`route` directive](/docs/caddyfile/directives/route).

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

@@ -0,0 +1,46 @@
+---
+title: error (Caddyfile directive)
+---
+
+# error
+
+Triggers an error in the HTTP handler chain, with an optional message and recommended HTTP status code. 
+
+This handler does not write a response. Instead, it's meant to be paired with the [`handle_errors`](handle_errors) directive to invoke your custom error handling logic.
+
+
+## Syntax
+
+```caddy-d
+error [<matcher>] <status>|<message> [<status>] {
+    message <text>
+}
+```
+
+- **&lt;status&gt;** is the HTTP status code to write. Default is `500`.
+- **&lt;message&gt;** is the error message. Default is no error message.
+- **message** is an alternate way to provide an error message; convenient if it is multiple lines.
+
+To clarify, the first non-matcher argument can be either a 3-digit status code, or an error message string. If it is an error message, the next argument can be the status code.
+
+## Examples
+
+Trigger an error on certain request paths, and use [`handle_errors`](handle_errors) to write a response:
+
+```caddy
+example.com {
+	root * /srv
+
+	# Trigger errors for certain paths
+    error /private* "Unauthorized" 403
+	error /hidden* "Not found" 404
+
+    # Handle the error by serving an HTML page 
+    handle_errors {
+        rewrite * /{http.error.status_code}.html
+		file_server
+    }
+
+	file_server
+}
+```

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

@@ -8,7 +8,12 @@ Sets up error handlers.
 
 When the normal HTTP request handlers return an error, normal processing stops and the error handlers are invoked. Error handlers form a route which is just like normal routes, and they can do anything that normal routes can do. This enables great control and flexibility when handling errors during HTTP requests. For example, you can serve static error pages, templated error pages, or reverse proxy to another backend to handle errors.
 
-A request's context is carried into error routes, so any values set on the request context such as [site root](/docs/caddyfile/directives/root) will be preserved in error handlers, too. Additionally, new placeholders are available when handling errors. [The JSON docs for an HTTP server's error routes](/docs/json/apps/http/servers/errors/#routes) describe these placeholders. The `handle_errors` directive simply adds error routes, so you can use those placeholders within a `handle_errors` block.
+A request's context is carried into error routes, so any values set on the request context such as [site root](root) will be preserved in error handlers, too. Additionally, new placeholders are available when handling errors. [The JSON docs for an HTTP server's error routes](/docs/json/apps/http/servers/errors/#routes) describe these placeholders. The `handle_errors` directive simply adds error routes, so you can use those placeholders within a `handle_errors` block.
+
+Note that certain directives, for example [`reverse_proxy`](reverse_proxy) which may write a response with an HTTP status which is classified as an error, will _not_ trigger the error routes.
+
+You may use the [`error`](error) directive to explicitly trigger an error based on your own routing decisions.
+
 
 ## Syntax
 
@@ -71,4 +76,4 @@ handle_errors {
 
 	respond "It's not a 4xx error."
 }
-```
+```