Integrated handling of trailing slashes in Gatsby

[pragmaticpat]

Using this feature

2022-FEB-08: This is now released in Gatsby 4.7: https://www.gatsbyjs.com/docs/reference/release-notes/v4.7/#trailingslash-option

The goal

Introduce trailing / non-trailing slash management as a baked-in feature of Gatsby ( no plugins required ).

What's the pain our users face?

• SEO: If the same content for a site is available via https://my.domain.io/about and https://my.domain.io/about/ and https://my.domain.io/about/index.html, which is possible to produce today with a Gatsby site, then Gatsby users suffer from reduced SEO since the search engine crawler will pick one of those URL's as the canonical URL. This can weaken the search ranking of the related content since it's limited to the traffic that goes to one of the possible URL's.
• Reporting: If the same content is available in multiple, then content editors and marketing teams are forced to perform some elaborate URL aggregation in their reporting tools to get a clear understanding about the traffic for each piece of content on their sites

How do users work around this today?

1. Redirects: Gatsby users can get around these problems via redirects, but redirects should be reserved for true path-level redirects ( e.g. redirect "/about/" to "/company/" ), not merely variations of the same path ( e.g. redirect "/about" to "/about/" ).
2. Plugins: Users also attempt to use gatsby-plugin-force-trailing-slashes and gatsby-plugin-remove-trailing-slashes to get the desired behavior, but are often left confused about how to achieve the desired outcome. See here for the depth of discussion that has occurred, to-date on the topic.

---

Gatsby users are looking for consistent treatment of URL's for their sites. As of November 2021, Gatsby only provides "forcing URL's to be a particular format" via Plugins ( which means, users must jump through a few hurdles to get consistent URL's in their sites).

---

Okay, so what do we do about this?

There are the following flavors of treatment that have been written about extensively in our open source project by community members, and by Gatsby employees alike:

• Force all URL's to include a trailing slash ( instead of "/about", "/about/" )
• Force all URL's to exclude a trailing slash ( instead of "/about/", "/about" )

Redirects, and expected behavior from the hosting provider ( e.g. Gatsby Cloud )

added to RFC on 2022-Jan-07

To ensure consistency within a given Gatsby site, as well as consistency across the various modes of running your Gatsby site ( e.g. develop, serve, and production ) hosting providers shall apply standard redirect behavior for sites that leverage the new trailingSlash option.

The following table not only specifies the redirect scenarios that will occur within gatsby develop, gatsby serve, and on Gatsby Cloud, but also specifies how other hosting providers should apply these redirects, given the settings specified for a given Gatsby site via gatsby-config.js.

Consider a page that exists at https://example.org/about/index.html

Scenario	trailingSlash value	Requested url	Redirect (hosting layer)	Rendered url
1	Ignore / not specified	/about	none	/about ( see ✨ )
2	Ignore / not specified	/about/	none	/about/
3	Ignore / not specified	/about/index.html	none	about/ ( see ✨ )
4	always	/about	301	/about/
5	always	/about/	none	/about/
6	always	/about/index.html	none	/about/
7	never	/about	none	/about
8	never	/about/	301	/about
9	never	/about/index.html	none	/about

✨ Gatsby Cloud searches for an appropriate path, and will render the corresponding page if found. It’s highly unlikely that the desired experience is to 404 a visitor when they attempt to access a resource with a different semantic than is configured ( e.g. attempting to access /about instead of /about/ should not 404 the visitor! ). Therefore, Gatsby Cloud makes additional attempts to get the visitor to the desired resource.

Why use a 301 redirect? Since the primary use case is that the website owners want all pages to follow a consistent semantic, this is not truly a temporary redirect. Therefore, a 301 seems most appropriate as the applied redirect when the website owners specify trailingSlash as either always or never.

While the techniques of implementing the Redirect and Rendered url may vary among providers, the outcome for the site owners and site visitors shall be consistent with the specification above.

What are we not including?

• Unfurl pages ( instead of "/about/" or "/about", "/about/index.html")

Approach

This feature will be purely additive, and the default behavior will be as Gatsby behaves today ( no opinion on whether you use trailing / non-trailing slashes ).

1. Introduce the option to force trailing slashes for all routes (including client routes) likely through a config setting in gatsby-config.js. API example:

   // gatsby-config.js
   module.exports = {
   	trailingSlash: "always"
   }

   The trailingSlash option would take three options: never, always, and ignore. never removes all trailing slashes, always adds it, and ignore doesn't automatically change anything and it's in user hands to keep things consistent. (Credit: SvelteKit has the same API)

2. Upon sufficient adoption, and critical bugs are addressed, we remove the flag and make this part of standard Gatsby behavior

3. Users can remove the corresponding force / remove trailing slash plugins from their Gatsby implementations

[jon-sully]

Ah great! Love to see this. Thanks for writing this up @pragmaticpat! I enjoyed our discussion on it some months ago and think this is a great framework to go off of. It's a hard but important issue to tackle given how much it touches!

and ignore doesn't automatically change anything and it's in user hands to keep things consistent

I love this third option in the API and I think it's exactly necessary for those sites that come from WordPress migrations, have a mix of trailing and non-trailing page variants, and other out-of-the-box builds. Great call out.

Would love to get my hands dirty on this one once it fulfills the RFC phase. Thanks again!

[pragmaticpat]

As mentioned in the initial RFC post above, we drew some inspiration from Sveltekit's API for how we'd present the option to users. A nuance here is that we don't explicitly call out the presence of automatic redirects when using the trailingSlash setting.

Saying it another way, given the RFC in its current state, it might be possible for a visitor to 404 when requesting /about/ when trailingSlash: never unless the user has also added the corresponding redirects. I question whether this is a desirable outcome.

For trailingSlash handling to be more "feature complete," perhaps we need to include some form of automated redirects so visitors don't 404 when they directly access a route as I described above ( understanding that some of this really would be best served in the chosen hosting layer ).

Prompt to the followers of this RFC

1. If we automatically handled/generated redirects in some way, do you think that's the right amount / too much "magic"?
2. Does it feel like some level of redirect automation is essential for this to be more "feature complete" from the user's perspective?

Thanks all!

[Khaledgarbaya]

You can follow the progress here.

[jon-sully]

Hey team 👋

I read through everything a few times and wanted to add my 2c.

but redirects should be reserved for true path-level redirects ( e.g. redirect "/about/" to "/company/" ), not merely variations of the same path ( e.g. redirect "/about" to "/about/" ).

Totally agree with this and love the sentiment.

Saying it another way, given the RFC in its current state, it might be possible for a visitor to 404 when requesting /about/ when trailingSlash: never unless the user has also added the corresponding redirects. I question whether this is a desirable outcome.

For trailingSlash handling to be more "feature complete," perhaps we need to include some form of automated redirects so visitors don't 404 when they directly access a route as I described above ( understanding that some of this really would be best served in the chosen hosting layer ).

I share your suspicion around how the outcome should feel for the developer — using 'Always' or 'Never' should be a pleasant experience. Classically, the "ah, it just works" moment would be the best, right? That said, I fervently agree that this should be handled in the hosting / server layer. I think setting up some kind of application-layer redirects to compensate for hosting-layer misconfigurations is a rabbit hole full of confusion and bad times 😅. I'd suggest that instead of that sort of magic we instead increase the amount of documentation around "how your selected web-server should behave". And that's not necessarily super a complex thing:

Your web-server should serve a file at path ~/public/foo-bar/index.html at example.com/foo-bar/ and should (server-level) redirect (301/302) a request to example.com/foo-bar to example.com/foo-bar/, easily checkable from a cURL or HTTPie request in your terminal.

If your web-server is serving the page content at both example.com/foo-bar and example.com/foo-bar/, you need to adjust your hosting preferences such that named directories that contain an index.html file are served as a trailing-slash-path for that directory and requests to that path without the trailing slash are redirected to the trailing slash variant.

For what it's worth, to my knowledge this is actually the default setup for every web-server I've seen (directories vs. documents is the history of the web) but for whatever reason these defaults get changed or adjusted by vendors or individuals etc. etc.

---

That all said, I think that particular thing (server trailing-slash / directory-document configuration), while outside of what Gatsby can actually control or deal with, is really important to making this whole project work.

As an example, if a Gatsby user sets up Gatsby (one way or another) so that Gatsby produces 'named index directories' (e.g. the resulting file is ~/public/my-path-name/index.html rather than ~/public/my-path-name.html), ensures that all calls to createPage() include a trailing slash in the path string to properly prep the Reach Router for trailing-slash-hydrations, and always passes a trailing-slash path to any usages of <Link> or other PWA-navigations (this 3-step setup is probably what this RFC's implementation would be for the always directive) the user could still run into problems if the web-server serves that file (~/public/my-path-name/index.html) at both example.com/my-path-name/ and example.com/my-path-name.

In the case where an end-user hits example.com/my-path-name/, great! All is well. In the case where the end-user hits example.com/my-path-name the web-server would serve the file and we'd see the weird flashing action so many have referenced. The file is statically rendered so should visually show the page to the user but once the Reach Router hydrates it realizes that it's not on the path it was configured for (that path had a trailing slash) so it flashes the page and moves the user over to the trailing slash variant. The result is both annoying (page flashing when cold-loading any page on the site [though subsequent PWA navigations should be okay]) and still wrong: the web-server is still serving (Gatsby-created) content on both the trailing and non-trailing URL path variants.

Obviously that's not Gatsby's fault — the 1,2,3 step controls are all Gatsby can do.. but that doesn't fix the issue or help the dev 😕.

---

Outside of adding docs around how the web-server should be setup in conjunction with using the always/never directives in this new RFC, the only other thing I could think of is perhaps adding HTML canonical tags to each page to represent the correct URL (pursuant to this RFC's flag) to compensate for possibly bad web-server setups. In those cases (bad web-server setup) the flashing / url-jumping could still happen but at least the SEO ought to be fully okay. Not a perfect sell, not a fix, but maybe a good second line of defense.

---

Finally, I think I know the answer but I just want to call out some behavior that may result of this RFC. If the developer has the directive always set but in their Gatsby-node.js (or otherwise) attempts to call createPage() and pass in a path of /static/example.html — explicitly passing in the .html filename, that will sort of bonk out and actually end up creating a file like ~/public/static/example.html/index.html? Meaning that the developer's intention of having a non-trailing-slash page even though the RFC directive was set to always is not possible, correct? I don't think it should be (and things would start getting pretty complex) but I just wanted to call it out. When it's always or never attempting to override that on specific pages is not supported and would make weird results.

E.g. the 404 page is basically the only page that lives outside of the trailing slash requirements (which is true today too) since it needs to be a document at ~/public/404.html

[pragmaticpat]

@jon-sully - as you'll see in the RFC, we've updated the spec to include expected behavior from hosting providers. This means that we'll be ensuring consistency from the setting ( trailingSlash ) specified by the developer all the way up through to the hosting layer.

Also, you'll see a couple of other details in the updated RFC:

1. We don't attempt to perform redirects when index.html is directly requested. The page will simply be served.
2. We are proposing the redirect defaults to a 301, since this use case is not for temporary redirection.

We'd love to hear your (and other followers of this RFC, of course!) thoughts on this as our default behavior

[jon-sully]

Very cool! All of the changes as of today (Jan-7-21) look awesome. Looks like a great opportunity for Gatsby Cloud to sneak in a couple of great 'it just works' features with the ✨ bits there — nice!

Really looking forward to playing with this as it progresses through its development phases. Thank you for all the hard work and reading my excessively long posts @pragmaticpat (and @LekoArts for some great dev!)! You guys rock.

[pragmaticpat]

I'd like to share that we have our first canary available for testing! 🚀 Thank you @LekoArts for leading the charge on this one.

[pragmaticpat]

Taking the canary through its paces. A couple of items to note ( some of which we've already discussed internally, but in the spirit of transparency! ... )

1. gatsby build && gatsby serve applies the desired trailing / non-trailing settings
2. gatsby develop doesn't yet operate according to the trailingSlash configuration ( known, in process )
3. 🤔 The rootpath seems to continue to apply a trailing slash in the sitemap (using gatsby-plugin-sitemap) and in the browser even when specifying trailingSlash: never

I've asked @LekoArts about the third item above.

Any other findings from folks that have tried this feature yet?

[LekoArts]

That the root path is having the trailing slash is perfectly fine :) If you go to e.g. https://github.com and log document.location.href in the console, you'll get a URL with a trailing slash.

Google says in their post https://developers.google.com/search/blog/2010/04/to-slash-or-not-to-slash

Rest assured that for your root URL specifically, http://example.com is equivalent to http://example.com/ and can't be redirected even if you're Chuck Norris.

[LekoArts]

We check if a path is / and then just pass it through, at those stages we don't know the final URL yet and thus can't change those root URLs. But it having this trailing slash it luckily not an issue 👍

[jon-sully]

Technically a root path can't not have a trailing slash 🙂 some browsers may hide it for brevity but an HTTP request sends a host + a path and the path can't be empty. Requesting my homepage sends a host of jonsully.net and a path of / — no way around that one! Just how the internet is built 😅

[slorber]

Hey, I probably come late to the party but you'll probably find this resource helpful :)

https://github.com/slorber/trailing-slash-guide

For what it's worth, we also have 3 values in Docusaurus and so far it seems to suit everyone's need for all hosting providers: https://docusaurus.io/docs/deployment#trailing-slashes

Note, for trailingSlash: 'never' you'd rather output about.html instead of /about/index.html

[pragmaticpat]

For each page in a Gatsby site, Gatsby generates a directory and an index.html within it, so the recommendation in the RFC will remain for scenario 9 at this point.

@slorber - If I missed your point (possible!) - please further explain. Thanks!

[slorber]

@pragmaticpat please look at the matrix on this page: https://github.com/slorber/trailing-slash-guide

If you still output /xyz/index.html for trailingSlash: 'never', an host like GitHub pages will redirect from /xyz to /xyz/, and there's no config option on GitHub page to prevent that.

See it for yourself live: https://slorber.github.io/trailing-slash-guide/folder

For sure you can still fix the URL client-side, but you will have URL flickering from /xyz to /xyz to /xyz, and I don't think the redirect would be good for SEO.

In this case, I believe it is better to output /xyz.html. This is what we do with Docusaurus and I believe this is the only way to support GitHub pages without trailing slashes reliably

---

Keep in mind that each host serves the HTML files differently (cf my repo above).

I believe the goal of Gatsby is still to avoid vendor lock-in to Gatsby cloud, and should allow deploying a static website to GitHub pages without trailing slashes in a reliable way.

You can't expect users to update the gatsby setting and things work everywhere by default unfortunately: the user must select a Gatsby setting that works fine for the selected deployment target and its current configuration.

We do so in the docusaurus docs:

https://docusaurus.io/docs/deployment

[pragmaticpat]

Great context again @slorber - we'll think through how best to proceed, including the info you shared above. Much appreciated!

[jon-sully]

Thanks for posting this @slorber! I think this helps illustrate the tension I was trying to tease out but couldn't quite draw a picture of — the inherent dependency of Gatsby on the hosting provider's (/ web server's) serving behavior and the necessary thought that needs to go into how/where Gatsby generates the specific named files to help accommodate various providers. Great chart!

[pragmaticpat]

Thanks again for sharing this information. It's important that we're considering how other hosts handle the various URL structures, as you noted @slorber .

For the first pass of this integrated feature, we're focusing on making things all work in Gatsby Cloud since we have such a naturally close relationship with the cloud product and can iron out all of the kinks there.

To make this feature compatible with other hosts, we'll likely do a couple of things:

1. Revise the spec so it does not imply that other well-established hosts should align with how Gatsby Cloud works ( these other well-established hosting solutions have an established behavior that their customers expect )
2. Incrementally support additional hosting behaviors through future revisions to the feature, and through community PR's if it's an urgent need for users attempting to leverage this feature on other hosts

[Artemdanilov5]

I have home page without slash: example.com
and if I go to with slash example.com/ it's redirecting and response 200, but should 301

[LekoArts]

Please see #34205 (comment) - this behavior is okay/the only one possible.

[pcarillion]

Hi @LekoArts and @pragmaticpat

Thanks for answering our questions.

I migrated a website to Gatbsy, hosted on Github Pages, and this website used to have a classical way to write paths (folders with / and files without).

I know it's not compulsory, but that's how it was and should stay because it can't afford duplicate content nor non-consistency.

Both @slorber and @jon-sully raised the issue (see below).

Do you think this issue is definitively closed on your side?

[LekoArts]

This is now released in Gatsby 4.7:
https://www.gatsbyjs.com/docs/reference/release-notes/v4.7/#trailingslash-option

[laurenskling]

After using this with always, my Gatsby Link components start pointing anchor links wrong.

<Link to="#contact /> will go the /#contact instead of /${currentPath}/#contact (which does happen in legacy mode)

[LekoArts]

For anchor links on the same page you should use the normal <a> element, <Link> is not intended for that.

[laurenskling]

that makes sense! I changed my code, thanks for the quick reply

[jon-sully]

Greetings All 👋

And for starters, a great big thank you for all the hard efforts spent trying to get Gatsby to have more finite control over the trailing slash patterns. It is greatly appreciated. Second, my own personal apologies for not having been more available while working through the direct development / canary process! I had a big voice on the matter; I wish I would've had more time in the development phase to help out more tangibly.

I've finally got some time to poke around and am updating my own Gatsby site to 4.7 (okay, 4.8. Y'all release fast! 😆) and wanted to share my notes on the trailing slash stuff. I have a couple of well-Google'd blog articles on the matter I'd like to update to current info as well, so this post will serve as my "findings / results" preceding an update to those blog posts.

Going to follow this process on both sides even though I only use trailing slashes. I've had a number of folks email me hoping for better guidance when not using slashes and I'm hoping that this turn-key approach will work great for all of them. This is from the perspective of upgrading a prior Gatsby app to >=4.7

Trailing Slashes Enabled

My steps:

1. Remove gatsby-plugin-force-trailing-slashes
2. Remove gatsby-plugin-force-trailing-slashes from Gatsby-config
3. (Optionally) go back through all 's and don't force them to end in /
   • Per my previous guidance, when going the "yes trailing slashes" route, Gatsby users would need to forcefully add a trailing slash to all PWA-navigation methods, be it <Link>, navigate(), etc.
4. Remove any forceful injection of / to the end of paths passed to createPage()
5. Add trailingSlash: 'always' to the top-level Gatsby-config export

Results

1. ✅ Pages are generated as named-directory's (path /foo/ is actually ~/public/foo/index.html)
2. ✅ Hosts following traditional file-based pathing respond correctly to slash/non-slash requests
   • More on this later, but e.g. Netlify (when default [Pretty URL's enabled]) or Gatsby Cloud
3. ✅ Gatsby correctly adds trailing slashes to paths given to <Link> components (but also doesn't add a second if the <Link> is already given a trailing-slash'd path)
4. 🟡 (A note but no real issue here) Internal links composed in markdown (via gatsby-transformer-remark) get a trailing slash added to the resulting link object in the DOM
   • This does not happen — the link in the DOM is verbatim what's in source, no trailing slash added. Left this one yellow instead of red because the behavior is 'okay' for non-JS users and just fine for JS users though:
   • Non-JS users: Because a blog post with a link in it, to say, example.com/blog/other-post will cause the user to hit example.com/blog/other-post then, provided you're using a well-setup web-server host, will 301 the user to example.com/blog/other-post/ (with the slash) because that's where the actual file is. The cost is an extra 301 jump.
   • JS-users: Because there's no actual full-page navigation and the Reach Router doesn't care about trailing slashes, the page (and page data) is executed immediately with no extra requests and the Reach Router ensures that the trailing slash is there after the navigation (or .. during? Not sure. There's no flash of un-slashed URL 👍)
5. ✅ Paths given to createPage() without a trailing slash appear to be computed as though they did have a trailing slash:
   • On the reach-router side once the page hydrates, the reach router isn't hot-swapping the URL in the address bar to a non-trailing-slash version
   • On the file side, the resulting files are indeed generated as named directories (already noted above)

Overall, for the yes-trailing-slash side of things, I'm quite happy with these results. There is still a LARGE dependency on the web-server serving files in a 'proper' way, but I believe most known web hosts either do this by default or can be configured to do so. I'd love to see the docs point it out just a little bigger than it currently is, but I appreciate nonetheless that it currently is and that this RFC maintains a table of expectations. In my opinion, @slorber's examples of how host's handle file structures is the gold-standard for showing and understanding host behavior with regard to serving files. It's actually similar to an illustrated deep-dive I did exclusively on Netlify's platform to show the same ideas.

All in all though, the yes-trailing-slashes config + Gatsby Cloud or Netlify hosting (@ defaults) = a good, working, intuitive setup, and that's a win. For a brand new Gatsby app and/or Gatsby user that hasn't dug into the finite components of web-hosting, this is about as turn-key as it gets. And for existing apps that are previously setup to use yes-trailing-slashes through any variety of means suggested previously, I would consider this to be a safe, solid migration forward. 👍

Trailing Slashes Disabled

This will be a bit unique because I have a few <Link> elements and tons of Markdown links that pass in a trailing-slash path explicitly. Let's see what happens!

My steps:

1. Remove gatsby-plugin-force-trailing-slashes
2. Remove gatsby-plugin-force-trailing-slashes from Gatsby-config
3. (Optionally) go back through all 's and don't force them to end in /
   • Per my previous guidance, when going the "yes trailing slashes" route, Gatsby users would need to forcefully add a trailing slash to all PWA-navigation methods, be it <Link>, navigate(), etc.
4. Remove any forceful injection of / to the end of paths passed to createPage()
5. Add trailingSlash: 'never' to the top-level Gatsby-config export

Results

1. 🟥 Pages are generated as named files rather than named directories
   • When running gatsby build with trailing slashes set to never, I'd expect a file such as ~/src/pages/contact.js to result in an output file of ~/public/contact.html so that it would be served at example.com/contact (or example.com/contact.html) per traditional web-server setups. Instead I'm seeing ~/src/pages/contact.js yield and output file of ~/public/contact/index.html, which is a trailing-slash file to any typical web-server.
2. 🟡 Hosts following traditional file-based pathing respond correctly to slash/non-slash requests
   • Yellow because technically the host is doing the right thing given the file structure yielded but the end-result is not what the Gatsby flag entails it should be
3. ✅ Gatsby correctly strips trailing slashes from paths given to <Link> components if necessary
4. 🟡 (A note but no real issue here either) Internal links composed in markdown (via gatsby-transformer-remark) get trailing slash removed if present
   • This does not happen — the link in the DOM is verbatim what's in source, no trailing slash removed. Left this one yellow instead of red because the behavior is 'okay' for non-JS users and just fine for JS users though:
   • Non-JS users: Because a blog post with a link in it, to say, example.com/blog/other-post/ will cause the user to hit example.com/blog/other-post/ then, provided you're using a well-setup web-server host (and (.1) above gets fixed), will 301 the user to example.com/blog/other-post (without the slash) because that's where the actual file is. The cost is an extra 301 jump.
   • JS-users: Because there's no actual full-page navigation and the Reach Router doesn't care about trailing slashes, the page (and page data) is executed immediately with no extra requests and the Reach Router ensures that the trailing slash is removed after the navigation (or .. during? Not sure. There's no flash of slashed URL 👍)
5. 🟥 Paths given to createPage() with a trailing slash appear to be computed as though they did have a trailing slash:
   • On the reach-router side once the page hydrates, we see a classic flash-of-slash issue. If you load the homepage things look fine, then since you're now in PWA mode (not doing actual page loads against the web-server) you can navigate around and the Reach Router will make sure that everything 'just works' and that none of the page addresses have trailing slashes — that's all fine. The problem is that when you refresh a given page (or copy the link to share with a friend), the browser will attempt to hit the server for the not-trailing-slash'd page, 301 you to the trailing-slash'd page, then the trailing-slash'd page will load and hydrate the router, then the router will remove the trailing slash dynamically. It's a flip-flop sequence that looks a little funky but also causes all refreshes (and shared links) to have to take a 301 jump before actually getting their content (hurting performance). As a tangible example, copy and paste this URL then carefully watch your address bar as it loads: https://deploy-preview-12--jonsully.netlify.app/blog
   • On the file side the same issue as (.1) above is causing issues (though this is the same as pre-v4.7) — passing a path of /blog/foo is creating a file of ~/public/blog/foo/index.html.

So, conclusion for the yes-trailing-slash side of things is that we're just one step away from everything working great. The files have to get produced in the right structure / format (not named directories) so that the web-server will respond the right way. I actually had someone email me this morning hoping for an answer on the not-trailing-slash front — I'm hopeful we can clear this one up and have great results on both sides of things!

Either way, this has come a long way and I'm really thrilled to see it through. Thank you again to all involved 🙌🏻

[jon-sully]

I feel it worth pointing out too that @slorber excellently made this note above on Jan.20 (emphasis mine)

If you still output /xyz/index.html for trailingSlash: 'never', an host like GitHub pages will redirect from /xyz to /xyz/, and there's no config option on GitHub page to prevent that.

See it for yourself live: https://slorber.github.io/trailing-slash-guide/folder

For sure you can still fix the URL client-side, but you will have URL flickering from /xyz to /xyz/ to /xyz, and I don't think the redirect would be good for SEO.

In this case, I believe it is better to output /xyz.html. This is what we do with Docusaurus and I believe this is the only way to support GitHub pages without trailing slashes reliably

And that is the very same behavior I'm seeing in action now (the 🟥's above). I too would advocate for this same workflow (bolded) ^ 👍

[pcarillion]

Thanks Jon for opening this discussion

[pragmaticpat]

@jon-sully - thanks for the thorough feedback! We'll see how we can incorporate the feedback into the feature going forward.

[slorber]

I'd suggest that you at least have a test deployment of Gatsby to GitHub pages and never, to ensure that it's always supported

That can probably be automated by pushing to a repo and doing a req to x.github.com/project/mypath => it should not lead to any server redirect

Apparently you didn't listen to my advice and it still doesn't work 😅

[pragmaticpat]

We're listening! Just didn't get to it yet. 😅 Stay tuned. Thanks for the nudge!

[moonmeister]

I'm curious how this is intended to affect functions? doest example.js function need to be served from /api/example and /api/example/ I'm guessing not from /api/example/index.html, correct?

[pragmaticpat]

Good question, @moonmeister - trailingSlash does not apply to functions.

[pragmaticpat]

I've submitted a light PR to clarify that in our Config API docs. Thanks again for raising the question.

[wad-im]

Hello,
I set trailingSlash: always on a simple blog website hosted on Gatsby cloud that I am currently working on. The sitemap is as expected consistent. However, when navigating via Link component on the page (clicking on the card leading to a post), I am being navigated to the page without trailing slash. Upon refresh though, it redirects to the page with trailing slash as expected.

I wonder now whether this behaviour is due to my set-up, browser behaviour or a bug.

Any help would be appreciated.

You can also find the repository here..

Thank you

[pragmaticpat]

@wad-im - thanks for reporting and sharing the repo - we'll take a look at this tomorrow morning ET and get back to you.

[pragmaticpat]

Thanks for raising this @wad-im - you uncovered an unhandled use case. Corresponding issue can be tracked here: #35419

[wad-im]

Thank you for looking into it.

[web-developer-areeb]

trailingSlash : "never" is working fine for /about but not working for /about.php

[pragmaticpat]

@web-developer-areeb - Can you please elaborate on the problem? Specifically:

1. What do you expect to have happen, and what is actually happening?
2. Your example includes a .php file - how does that relate to Gatsby and this particular feature?

[web-developer-areeb]

It is not working on localhost but it worked on live. Thanks.

Reply:
English and other countries site is in php. I made the french site in Gatsby. So client wants urls of some pages with .php in the end to give user same feel. So I wrapped the index.js file of those pages in pagename.php folder.
I wanted to remove trailing slash. And traling slash was removed by trailingSlash: "never"
But pages whose name is pagename.js or index.js wrapped in pagename folder is working fine and pages with .php in the end either made by pagename.php.js or index.js wrapped in pagename.php is showing blank page with error below:

This page isn’t workinglocalhost redirected you too many times.
Try clearing your cookies.
ERR_TOO_MANY_REDIRECTS

PS: It worked on live site that enogh for me. :)

[Artemdanilov5]

@LekoArts

I have gatsby website that hosted on gatsby cloud. I use new option of gatsby "trailingSlash: "always":

module.exports = {
    trailingSlash: "always",
}

I use default config gatsby-plugin-gatsby-cloud without any options.

After gatsby build all my static files with slash at the end have status code 200, but should 404. If I use gatsby serve on localhost it's working good and I get 404.

Example: website.com/static/img.jpg/

But if I use "never" option I get 301 redirect from website.com/static/img.jpg/ to website.com/static/img.jpg and I think it's better than 200, but still need to get 404.

module.exports = {
    trailingSlash: "never",
}

I've noticed this problem on many gatsby sites including starter-blog-theme: https://github.com/gatsbyjs/gatsby-starter-blog-theme

Reproduction Link

https://www.leaftfoods.com/static/8d8cfc95f97e007180db73d4464271af/2432c/3daddde8-33e9-4722-8775-ff1e409641d8_field_-16.jpg/

[hitfactory]

I got redirected here from #37536.

@LekoArts I'm using the trailingSlash never option, but the way this is handled means that my sitemap does not include the canonical URL of the site's homepage.

I don't this understand how this can be considered acceptable since the whole purpose of a sitemap is to include the canonical URLs which should be indexed for a site.

[randychilau]

Good day everyone.

I could not find a working example online of a Gatsby site hosted on GitHub Pages that works without a trailing slash / no-trailing-slash.

For anyone who is looking for one, here are two urls:

https://no-trailing-slash.github.io

https://randychilau.github.io/gatsby-no-trailing-slash-github-pages

---

Question: Why two urls?
Answer: When I created the repo gatsby-no-trailing-slash-github-pages in my GitHub account, it is considered a "project" site:

The source files for a project site are stored in the same repository as their project. Unless you're using a custom domain, project sites are available at http(s)://<username>.github.io/<repository> or http(s)://<organization>.github.io/<repository>. source

When you go to http(s)://<username>.github.io/<repository>, it will show http(s)://<username>.github.io/<repository>/ in the browser address bar, and I thought that would look strange for a post about no-trailing-slashes. I believe this is because the repository is a subdirectory, even though it is the root folder for the project? and there is nothing that can be done to avoid this? (I am unsure, please feel free to correct/educate me on this).

But if I created a "user" site, then you can see a site with the no-trailing-slash experience from start to finish, so I created a personal account no-trailing-slash and imported the code to a repository named no-trailing-slash.github.io that would be accessible at https://no-trailing-slash.github.io as per these instructions:

To publish a user site, you must create a repository owned by your personal account that's named .github.io. To publish an organization site, you must create a repository owned by an organization that's named .github.io. Unless you're using a custom domain, user and organization sites are available at http(s)://.github.io or http(s)://.github.io. source

hope that makes some sense.

---

And the sitemaps:
https://no-trailing-slash.github.io/sitemap-0.xml
https://randychilau.github.io/gatsby-no-trailing-slash-github-pages/sitemap-0.xml

Here is the repo with the code and the overly detailed README:
https://github.com/randychilau/gatsby-no-trailing-slash-github-pages

Please feel free to ask me any questions, provide feedback on any of the writings, suggest alternatives, etc.

As stated in the README, but bears repeating:
Credit: slorber, jon-sully, gatsby-plugin-meta-redirect, Gatsby Team, everyone on "the threads" [1][2]

Cheers!