Redirect Plugin for Markdown Pages in Gatsby

5/22/2020

• updated 5/23/2020

Plugin for Gatsby to create redirects based on a list in your Markdown frontmatter, mimicking the behavior of jekyll-redirect-from.

Redirect Plugin for Markdown Pages in Gatsby

Features

By adding a redirect_from list of URLs to your Markdown file’s YAML frontmatter, this plugin creates client-side redirects for all of them at build time, with Gatsby’s createRedirect used under the hood.

By combining this plugin with gatsby-plugin-meta-redirect you get simple server-side redirects from your redirect_from lists out of the box. You can also combine it with any other plugin picking up Gatsby createRedirect calls to get proper SEO-friendly server-side redirects for your hosting provider.

Usage

First, install the plugin from your project’s root:

cd yourproject/
npm i gatsby-redirect-from gatsby-plugin-meta-redirect

Then add it to your gatsby-config.js file under plugins:

plugins: [
  'gatsby-redirect-from',
  'gatsby-plugin-meta-redirect' // make sure this is always the last one
]

That’s it for the configuration.

Finally, use the key redirect_from followed by a list in your Markdown file’s YAML frontmatter:

---
title: Aperture File Types
redirect_from:
  - /new-goodies-aperture-file-types-icons/
  - /goodie-updated-aperture-file-types-v11/
  - /aperture-file-types-v12-released/
  - /2008/04/aperture-file-types/
  # note: trailing slashes are required
---

Default Query

Plugin assumes the default setup from gatsby-starter-blog, with Markdown files processed by gatsby-transformer-remark, and adding a field slug for each markdown node. Resulting in the availability of a allMarkdownRemark query.

Head over to gatsby-starter-blog’s gatsby-node.js file to see how this is done, or follow the Adding Markdown Pages tutorial.

Optionally, you can pass a different query to this plugin’s configuration.

Server-Side Redirects

Gatsby’s createRedirect only creates client-side redirects, so further integration is needed to get SEO-friendly server-side redirects or make your redirects work when users have JavaScript disabled. Which is highly dependent on your hosting provider: if you want to have the proper HTML status codes like 301, Apache needs .htaccess rules for that, Nginx needs rewrite rules, S3 needs RoutingRules, Vercel needs entries in a vercel.json, Netlify needs a _redirects file, and so on.

One simple way, as suggested by default in installation, is to use gatsby-plugin-meta-redirect to generate static HTML files with a <meta http-equiv="refresh" /> tag for every createRedirect call in their <head>. So it works out of the box with this plugin without further adjustments.

This way is the most compatible way of handling redirects, working with pretty much every hosting provider. Only catch: it’s only for usability, no SEO-friendly 301 redirect is set anywhere.

For some hosting providers additional plugins are available which will pick up the redirects created by this plugin and create server-side redirects for you. Be sure to add any of those plugins after gatsby-redirect-from in your gatsby-config.js:

Provider	Plugin
Netlify	gatbsy-plugin-netlify
Vercel	gatsby-plugin-zeit-now
AWS S3	gatsby-plugin-s3
Nginx	gatsby-plugin-nginx-redirect
Apache	gatsby-plugin-htaccess-redirects

Options

Plugin does not require to be configured but additional customization options are available:

Option	Default	Description
`query`	`allMarkdownRemark`	Modify the query being used to get the frontmatter data. E.g. if you use MDX, set `allMdx` here.

Add options to the plugins’s configuration object in gatsby-config.js like so:

plugins: [
  {
    resolve: 'gatsby-redirect-from',
    options: {
      query: 'allMdx'
    }
  },
  'gatsby-plugin-meta-redirect' // make sure this is always the last one
]