# Plugin – lektor-redirect 0.1.0b2

A Lektor plugin to help with generating redirects for, e.g., moved pages.

#### Project links

#### Meta

Version: 0.1.0b2

Author: Jeff Dairiki

#### Tags

before-build-all, and setup-env

View all tags.

## Project Description

# lektor-redirect

This plugin allows pages (and attachments) to specify alternative/old URLs which should redirect to their current location.

> [!IMPORTANT] Currently this plugin will not work on Lektor sites with alternatives enabled.

## How it works

The plugin looks for a field named (by default) `redirect_from` on pages and attachments in the site. This field is expected to contain a sequence of URLs to redirect from.

There are two ways that redirects may be implemented by this plugin. Either or both may be enabled.

### Redirect pages

Redirect pages can be generated at the specified URLs. The template for these pages is up to you, however the intent is that these pages will attempt an meta refresh and/or javascript redirect to the target page.

### Redirect map

A redirect map file can be generated. This may be used to configure your web server to issue the desired redirects itself. (Currently only an nginx-style map is supported.)

## Usage

By default the plugin looks for a field named `redirect_from` on pages in the site. (The name of the field may be customized in the plugin configuration file. See below.) This field should contain a sequence of URLs to redirect from — most likely it should have a field type of `strings`.

E.g. To be able to generate redirects to your pages, you might add the following field to your `models/page.ini` file:

    [fields.redirect_from]
    label = Redirect From
    description = Other URLs which should redirect to this page
    type = strings

The URLs in the `redirect_from` field may either be absolute (beginning) with a slash (these are interpreted relative to the root of the site) or they may be relative, in which case they are interpreted relative to the URL of the parent of the page containing the `redirect_from` field.

As an example, if the is a page at lektor path `/blog/first-post`, who’s URL, if nothing exotic is done with slug configuration is `/blog/first-post/`, then, if `first-posts`’s `redirect_from` is set to `test-post`, then:

- If redirect page generation is enabled, there will be an artifact generated at in `/blog/test-post/index.html` which will, hopefully, redirect the user to `/blog/first-post/`.

- If redirect map generation is enabled, it will include an entry mapping `/blog/test-post` to `/blog/first-post/`.

### Configuration File

The plugin's configuration file is `configs/redirect.ini`. Settings should be in a `[redirect]` section. There are currently three configurable settings. Here is an example:

    [redirect]
    # The name of the field from which redirects are extracted.
    # The default value is "redirect_from"
    redirect_from_field = redirect_from

    # Set template used to render redirect pages.
    # There is no default value — if no template is set, redirect
    # page generation is disabled.
    template = redirect.html

    # Set the name of the redirect map file.
    # There is no default value — if no value is set, redirect
    # map generation is disabled.
    map_file = .redirect.map

### Redirect Pages

If a `template` is configured in the plugin configuration file (`configs/redirect.ini`), redirect pages will be generated from the specified template. The intention is that the resulting page will redirect the user to the target location using meta refresh and/or a javascript redirect.

Within the template, the target of the redirect is available as `this.target`.

An simple example for such a template is:

    <!doctype html>
    <html>
      <head>
        <title>Page Moved</title>
        <link rel="canonical" href="{{ this.target|url(external=true) }}">

        <!-- meta refresh redirect -->
        <meta http-equiv="refresh" content="0; url={{ this.target|url(absolute=true) }}">

        <!-- javascript redirect -->
        <script type="text/javascript">
         window.location.href = {{ this.target|url(absolute=true)|tojson }};
        </script>
      </head>
      <body>
        <h1>Page Moved</h1>
        <p>
          If you are not automatically redirected, the page you want can be found at
          <a href="{{ this.target|url }}">{{ this.target|url(external=true) }}</a>.
        </p>
      </body>
    </html>

> [!TIP] For the `url(external=true)` and `url(absolute=true)` filters to work, a `[url][project config]` may need to be configured for the project.

When redirecting from URLs that do not end with `.html` or `.htm`, the redirect page is generated at the url with `/index.html` appended. For example if there is a redirect from `/old-image.png` to `/new-image.png`, the redirect page will be generated at `/old-image.png/index.html`. This is done with the hope that the web server, without extra configuration, will respond to a request for `/old-image.png` with a content-type header of `text/html`.

### Redirect Map

If a `map_file` is configured in the plugin configuration file (`configs/redirect.ini`), a map file will be generated in the output tree.

The map file is in a format suitable for inclusion in an nginx map block. Assuming there is a single redirect from `/old-page` to `/new-page`, the contents of the map file would be:

    /old-page/ /replacement-page/;

Assuming that `map_file` is set to `.redirect.map`, the salient parts of an nginx configuration file that utilizes the redirect map might look like:

    [...]

    http {
        [...]

        # You may need to adjust this (and/or map_hash_max_size) to avoid
        # "could not build map_hash, you should increase map_hash_bucket_size"
        # error from nginx
        map_hash_bucket_size 128;

        map $uri $redirect_to_uri {
            default "";
            include /path/to/htdocs/.redirect.map;
        }

        server {
            listen [...];
            [...];

            root /path/to/htdocs;

            location ~ /\. {
                # Don't serve dot-files (like .redirect.map)
                return 404;
            }

            if ($redirect_to_uri) {
                # pass query args to preserve utm_* tracking parameters, etc.
                return 301 $redirect_to_uri$is_args$args;
            }

            [...]
        }
    }

## To Do

- Make this work for Lektor projects with alternatives enabled.

- Add support for writing the redirect map file in other formats. (E.g. Apache text map format.)

## Author

Jeff Dairiki dairiki@dairiki.org

## Comments