From 4b44b38d846164efb41f30ec43268221594ba16f Mon Sep 17 00:00:00 2001
From: Armin Ronacher <armin.ronacher@active-4.com>
Date: Tue, 29 Dec 2015 11:52:27 +0100
Subject: [PATCH] Added guide on error pages

---
 content/docs/guides/error-pages/contents.lr | 71 +++++++++++++++++++++
 1 file changed, 71 insertions(+)
 create mode 100644 content/docs/guides/error-pages/contents.lr

diff --git a/content/docs/guides/error-pages/contents.lr b/content/docs/guides/error-pages/contents.lr
new file mode 100644
index 00000000..ce16a672
--- /dev/null
+++ b/content/docs/guides/error-pages/contents.lr
@@ -0,0 +1,71 @@
+title: Error Pages
+---
+summary: Brief introduction into error pages in Lektor.
+---
+body:
+
+Because Lektor renders out static pages the question comes up what happens if a
+page cannot be found.  This is typically achieved by a special page that a
+server will then use as a stand-in for a page that otherwise cannot be found.
+
+In Lektor as a convention this page should be called `404.html`.  While in
+reality the name of this page largely depends on how you deploy your pages we
+are sticking with the generally accepted location of calling it `404.html`.
+This will work on GitHub Pages and some other environments where this cannot
+be otherwise configured and most web servers can be configured to use this file
+for URLs that are not found.
+
+! In versions of Lektor before 2.0 custom 404 pages will not be honored by the
+development server.  To test those you will need to explicitly navigate to
+`/404.html`.
+
+## URLs on 404 Pages
+
+If you are using 404 pages then these pages can appear at any URL.  This means
+that relative URLs *will not work*.  If you want to use custom error pages you
+will have to set the `url_style` to `absolute` as otherwise URLs on an error
+page will not work.  Just add this to your project file:
+
+```ini
+[project]
+url_style = absolute
+```
+
+For more information about this you can read the [Project File Documentation
+:ref](../../project/file/).
+
+## Server Configuration
+
+If you are deploying such pages to your own servers you will need to ensure
+that the error pages are activated.  Depending on the server used this will
+work slightly differently.
+
+### Apache
+
+Making custom error pages work is easiest with Apache.  If `.htaccess` files
+are enabled you can just put a file with that name into your `assets` folder
+and add the following line to it:
+
+```apache
+ErrorDocument 404 /404.html
+```
+
+Alternatively you can add the above line into a `VirtualHost` or `Directory`
+section in your main config file.
+
+### nginx
+
+For nginx you need to enable the error document in your main config file.  Just
+add it to your `server` section:
+
+```nginx
+error_page 404 /404.html;
+```
+
+### lighttpd
+
+If you are using lighttpd you can configure an error page for 404 this way:
+
+```ini
+server.error-handler-404 = "/404.html"
+```