From 5f028df5dc4a68ab1d97cff8b566ddf91d279846 Mon Sep 17 00:00:00 2001 From: Matthew Holt Date: Wed, 3 Jun 2020 12:19:30 -0600 Subject: [PATCH] docs: Improve handle_errors docs; add examples --- .../caddyfile/directives/handle_errors.md | 35 ++++++++++++++++++- 1 file changed, 34 insertions(+), 1 deletion(-) diff --git a/src/docs/markdown/caddyfile/directives/handle_errors.md b/src/docs/markdown/caddyfile/directives/handle_errors.md index 5761789..f855052 100644 --- a/src/docs/markdown/caddyfile/directives/handle_errors.md +++ b/src/docs/markdown/caddyfile/directives/handle_errors.md @@ -6,7 +6,9 @@ title: handle_errors (Caddyfile directive) 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. +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. ## Syntax @@ -17,3 +19,34 @@ handle_errors { ``` - **** is a list of HTTP handler directives, directive blocks, or matchers; one per line. + + + +## Examples + +Custom error pages based on the status code (i.e. a page called `404.html` for 404 errors): + +```caddy +handle_errors { + rewrite * /{http.error.status_code}.html + file_server +} +``` + +A single error page that uses [`templates`](/docs/caddyfile/directives/templates) to write a custom error message: + +```caddy +handle_errors { + rewrite * /error.html + templates + file_server +} +``` + +Reverse proxy to a local backend equipped to handle errors: + +```caddy +handle_errors { + reverse_proxy localhost:9000 +} +```