Skip to main content

Adding a Path Prefix

Many sites are hosted at something other than the root of their domain.

E.g. a Gatsby blog could live at or a site could be hosted on GitHub Pages at

Each of these sites need a prefix added to all paths on the site. So a link to /my-sweet-blog-post/ should be rewritten to /blog/my-sweet-blog-post.

In addition links to various resources (JavaScript, images, CSS) need the same prefix added (this is accomplished by setting the publicPath in webpack).

Luckily, for most sites, this work can be offloaded to Gatsby. Using Gatsby’s Link component for internal links ensures those links will be prefixed correctly. Gatsby ensures that paths created internally and by webpack are also correctly prefixed.


During development, write paths as if there was no path prefix e.g. for a blog hosted at, don’t add /blog to your links. The prefix will be added when you build for deployment.

Production build

There are two steps for building a site with path prefixes.

First define the prefix in your site’s gatsby-config.js.

module.exports = {
  // Note: it must *not* have a trailing slash.
  pathPrefix: `/blog`,

Then pass --prefix-paths cmd option to Gatsby.

gatsby build --prefix-paths

NOTE: When running the command without the --prefix-paths flag, Gatsby ignores your pathPrefix.

Edit this page on GitHub