lektor-website/content/docs/guides/error-pages/contents.lr

87 lines
2.6 KiB
Markdown

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/).
## Creating an Error Page
You can easily add a 404 page by creating a `404.html/contents.lr`
file. If you do not care much about the contents and structure of the file
you can just point it to an empty model (`none`) and manually select a
`404.html` template like this:
```
_model: none
----
_template: 404.html
```
Then just create a `404.html` template with the intended contents.
## 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"
```