Skip to content

Conversation

@jaygiang
Copy link
Collaborator

@jaygiang jaygiang commented Nov 21, 2025

We currently have 2,044 internal links that hit redirects due to a mismatch between Docusaurus (which adds trailing slashes) and Vercel (which removes them). This wastes Google's crawl budget during indexing, particularly important after our .sh to .com migration.

The fix is setting trailingSlash: false in Docusaurus to match Vercel's behavior. This eliminates the redirect chains that where ending in trailing slash.

Related Issue or Design Document

Removed trailing slashes from static urls - #2352

Architecture Changes

Setting trailingSlash: false changes how Docusaurus generates files:

Before: docs/polis/index.mdxbuild/docs/polis/index.html → URL: /docs/polis/
After: docs/polis/index.mdxbuild/docs/polis.html → URL: /docs/polis

Instead of creating folders with index.html files, it creates individual HTML files. Are you aware of any potential risks?

Post-Deployment Monitoring

After going live, we need to check:

  • Server logs for any 404 errors
  • Analytics to ensure tracking still works
  • Google Search Console for crawl errors
  • Run an Ahrefs crawl to confirm redirects are gone

Changes in this PR

  1. Set trailingSlash: false in docusaurus.config.ts
  2. Fixed one broken link that needed .mdx extension
  3. Removed elements/reference/index.mdx (conflicted with generated-index)

Checklist

  • I have read the contributing guidelines and signed the CLA.
  • I have referenced an issue containing the design document if my change introduces a new feature.
  • I have read the security policy.
  • I confirm that this pull request does not address a security vulnerability.
    If this pull request addresses a security vulnerability,
    I confirm that I got approval (please contact security@ory.com) from the maintainers to push the changes.
  • I have added tests that prove my fix is effective or that my feature works.
  • I have added the necessary documentation within the code base (if appropriate).

Further comments

vinckr

This comment was marked as resolved.

Copy link
Member

@vinckr vinckr left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

looks good to me i guess, didn't check everything of course but at a cursory glance everything seems to be working and this doesn't really have any obvious effect.

i was a bit confused by the elements/reference/index - why was there even there in the first place? but https://www.ory.com/docs/elements/ works the same as before

@jaygiang jaygiang requested a review from jonas-jonas November 21, 2025 20:40
@jaygiang jaygiang merged commit 1408eea into master Nov 21, 2025
9 checks passed
@jaygiang jaygiang deleted the fix/redirects-trailingslash branch November 21, 2025 22:07
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants