Use Custom Paths in Gatsby
Tags: gatsby, react, javascript, webdev
Published: 2019-11-18 16:00:38

---
title: Use Custom Paths in Gatsby
published: true
description: Learn how to customize your page paths in Gatsby
tags: gatsby, react, javascript, webdev
cover_image: https://res.cloudinary.com/dovoq8jou/image/upload/v1573083623/articles/gatsby-custom-paths.png
canonical_url: https://stevenmercatante.com/use-custom-paths-in-gatsby
---

___
*This post was originally published at [stevemerc.com](https://stevenmercatante.com/use-custom-paths-in-gatsby)*
___

By default, Gatsby generates URLs for posts from their filename (or the directory name, depending on how you organize your posts). For example, if your post is named `gatsby-custom-paths.md`, its URL will be `https://mysite.com/gatsby-custom-paths`.

But what if you want to use a different URL (say, `use-custom-paths-in-gatsby`) without changing the post's filename? That's the problem I ran into. I have a specific naming and organization convention for my posts that should be independent of their URL.

Luckily, we can change how these URLs are generated.

## The Solution

First, add a `path` attribute to the frontmatter for any post whose URL you want to customize. Here's the frontmatter for this post:

```yml
---
title: Use Custom Paths in Gatsby
path: 'use-custom-paths-in-gatsby'
---

```

_Make sure you restart the Gatsby dev server after adding new fields to frontmatter for the first time, otherwise you won't be able to query them._

You can control how page URLs are generated by overriding the [`onCreateNode`](https://www.gatsbyjs.org/docs/node-apis/#onCreateNode) function in `gatsby-node.js`. Here's what my implementation looks like (yours may differ; the important thing is to see that `slug` is generated by `createFilePath`.)

```javascript
// gatsby-node.js

exports.onCreateNode = ({ node, getNode, actions }) => {
  const { createNodeField } = actions

  if (node.internal.type === 'Mdx') {
    const slug = createFilePath({ node, getNode })
    createNodeField({
      node,
      name: 'slug',
      value: slug,
    })
  }
}
```

Remember when we added that `path` attribute to our post's frontmatter ealier? We're gonna refer to it here. Update your `slug` definition to use `node.frontmatter.path` or fallback to the `createFilePath` invocation.

```javascript
// gatsby-node.js

exports.onCreateNode = ({ node, getNode, actions }) => {
  ...

  if (node.internal.type === "Mdx") {
    let slug = node.frontmatter.path || createFilePath({ node, getNode })
    ...
  }
}
```

Restart your Gatsby dev server again, and it'll regenerate the slugs. If you added a custom `path` to any of your posts's frontmatter, you'll now be able to access them via that custom path. In our case, we can now access this post by going to [`https://stevemerc.com/use-custom-paths-in-gatsby`](https://stevemerc.com/use-custom-paths-in-gatsby).

## Caveats

One of the nice things about having Gatsby autogenerate slugs/paths is that you'll never have two identical URLs for posts since you can't have identically named files or directories. Using this custom method, you need to make sure you don't use the same path for different posts.

👋 **Enjoyed this post?**

Join my [newsletter](https://stevemerc.com/newsletter/?r=dev) and follow me on Twitter [@mercatante](https://twitter.com/mercatante) for more content like this.