Redirect Old URLs in Jekyll

Changing a Jekyll post’s title, date, or permalink can leave old links pointing at a 404 page. The jekyll-redirect-from plugin creates small redirect pages so those URLs still lead somewhere useful.

Add the gem to your Gemfile:

gem "jekyll-redirect-from"

Then install the bundle:

bundle install

You can also install the gem directly:

gem install jekyll-redirect-from

Enable it in _config.yml:

plugins:
  - jekyll-redirect-from

Jekyll versions before 3.5.0 use the gems key instead of plugins. If you run Jekyll in safe mode to mimic GitHub Pages, add the plugin to the whitelist too:

whitelist:
  - jekyll-redirect-from

Give a post its old paths

Add redirect_from to the post’s front matter. It accepts several previous URLs:

title: My amazing post
redirect_from:
  - /post/123456789/
  - /post/123456789/my-amazing-post/

A trailing slash changes the generated output. This value:

redirect_from:
  - /post/123456789/my-amazing-post/

generates:

/post/123456789/my-amazing-post/index.html

Without the trailing slash, the plugin generates a file without an extension or subdirectory:

/post/123456789/my-amazing-post

Both pages contain an HTML refresh that points to the post’s current URL. You can also supply a single path without an array:

title: My other post
redirect_from: /post/123456798/

The plugin uses site.url and site.baseurl when it builds the target. That matters when the site lives below the domain root. On GitHub Pages, the Pages domain or a custom CNAME is used when site.url is not configured.

Redirect to another website

For an external destination, use redirect_to:

title: My project
redirect_to: https://github.com/

Redirects on collection items only work for files that Jekyll outputs as HTML, such as Markdown, Textile, and HTML documents.

Customise the redirect page

Create _layouts/redirect.html if you want to replace the plugin’s default redirect template. The layout receives two useful values:

• page.redirect.from is the relative path of the generated redirect page.
• page.redirect.to is the target’s absolute URL when one is available.

This plugin uses an HTML refresh rather than a server-level HTTP redirect. If the host lets you configure real redirects, I would normally prefer those. On GitHub Pages, though, jekyll-redirect-from is a practical way to stop old links from quietly rotting.

← Back to all articles