Redirect plugin for Markdown Pages in Gatsby

published • updated

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


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.


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-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
  - /new-goodies-aperture-file-types-icons/
  - /goodie-updated-aperture-file-types-v11/
  - /aperture-file-types-v12-released/
  - /2008/04/aperture-file-types/
  # note: traling 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


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

#Check out & contribute

Head over to GitHub for more documentation, take a peek into the code, or to report some bugs.



sourced from kremalicious/


All notable changes to this project will be documented in this file. Dates are displayed in UTC.

Generated by auto-changelog.


23 May 2020


22 May 2020


17 May 2020

  • Bump release-it from 12.6.3 to 13.6.0 #20
  • Bump eslint-config-prettier from 4.3.0 to 6.11.0 #19
  • Bump eslint from 5.16.0 to 7.0.0 #18
  • Bump chalk from 2.4.2 to 4.0.0 #17
  • Bump prettier from 1.19.1 to 2.0.5 #15
  • Bump cross-env from 5.2.1 to 7.0.2 #16
  • Bump auto-changelog from 1.16.4 to 2.0.0 #14
  • fix typo on documentation #13
  • Release 0.2.2 265be4c
  • bump more packages 1341254
  • formatting changes b8322b2


10 June 2019


10 June 2019

  • Update docs & dependencies #12
  • specify node 8 instead of 10 as engine #11
  • Support alternative markdown queries (such as allMdx) #10
  • Update release-it to the latest version 🚀 #8
  • update docs, mention new options 07835d8
  • simplify release-it tasks, add changelog 3ec4ccf
  • add prettier 3f33f65


30 August 2018

  • integrate with gatsby-plugin-meta-redirect, notes on server rendering 2cd07ee
  • Release 0.1.1 e72d5ab


30 August 2018


29 August 2018


29 August 2018