Skip to main content
Community Plugin
View plugin on GitHub
See starters using this

gatsby-plugin-slug

Add slug field to MarkdownRemark and Mdx nodes

npm package

By default gatsby generate url by following directories structure.

For example, the following directory structure generate path url mysite.com/2018/08/my-first-post

2018
  ↳ 08
    ↳ my-first-post

With the same directory structure using gatsby-plugin-slug, you can add a custom slug field to MarkdownRemark and Mdx nodes to have custom urls like mysite.com/super-post

Getting started

gatsby-plugin-slug

You can download gatsby-plugin-slug from the NPM registry via the npm or yarn commands

yarn add gatsby-plugin-slug
npm install gatsby-plugin-slug --save

Usage

  1. Add the plugin in your gatsby-config.js file:
module.exports = {
  plugins: ["gatsby-plugin-slug"],
}
  1. (Optional) Add slug field in the frontmatter of your markdown files:
---
slug: my-custom-slug
---
  1. Use the slug field for the path key when you create a new page in you gatsby-node.js:
const blogPostTemplate = path.resolve("./src/templates/post.js")

exports.createPages = ({graphql, boundActionCreators}) => {
  const {createPage} = boundActionCreators
  return new Promise((resolve, reject) => {
    resolve(
      graphql(
        `
          {
            posts: allMarkdownRemark() {
              nodes {
                fields {
                  slug
                }
              }
            }
          }
        `
      ).then(result => {
        const posts = result.data.posts.nodes
        posts.forEach(post => {
          createPage({
            path: post.fields.slug,
            component: blogPostTemplate,
            context: {
              slug: post.fields.slug,
            },
          })
        })
      })
    )
  })
}
  1. Use the slug in the context to get more data:
import React from "react"

const PostTemplate = ({data: {post}}) => (
  <div>
    <h1>{post.title}</h1>
    <div dangerouslySetInnerHTML={{__html: post.html}} />
  </div>
)

export default PostTemplate

export const pageQuery = graphql`
  query PostBySlug($slug: String!) {
    post: markdownRemark(fields: {slug: {eq: $slug}}) {
      html
      frontmatter {
        title
      }
    }
  }
`

Contributing

  • ⇄ Pull/Merge requests and ★ Stars are always welcome.
  • For bugs and feature requests, please create an issue.

See CONTRIBUTING.md guidelines

Changelog

See CHANGELOG.md

License

This project is licensed under the MIT License - see the LICENCE.md file for details

Docs
Tutorials
Plugins
Blog
Showcase