-
Notifications
You must be signed in to change notification settings - Fork 430
chore: canonical forward slash #2307
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Conversation
…d OAuth2 documentation
…ove troubleshooting index document
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thank you for the PR! Unfortunately, all links in the docs must be relative, otherwise many things break:
- Links will keep working on the GitHub interface and many Markdown editors
- You can customize the files' slugs without having to update all the links
- Moving files around the folders can be tracked by your editor, and some editors may automatically update file links
- A versioned doc will link to another doc of the exact same version
- Relative URL links are very likely to break if you update the trailingSlash config
Please also read: https://docusaurus.io/docs/markdown-features/links
If you find broken links please resolve them with the relative path structure.
To achieve what you want, there should be other solutions, such as turning off auto-generation of the categories you don't want. This is all possible using Docusaurus and should be possible to read up on in the Docusaurus docs!
Also please append (to the end) all redirects into https://github.com/ory/docs/blob/master/vercel.json since the docusaurus redirects are only JS redirects.
…nto chore/canonical-forward-slash
Thanks @aeneasr for your review! The changing to absolute paths wasn't the right approach. Appreciate you sharing the docs and context! After digging into it more, realized the issue is specifically with index files and directory-named files. It looks like Docusaurus automatically adds trailing slashes to those in production. These specific files match up with the canonical errors we are seeing in Ahrefs. Pattern 1: Index Files
Pattern 2: Directory-Named Files
Updated this PR and created a reusable |
@aeneasr Oh yes I can see the confusion. The issue isn't with the URLs themselves. The problem is in the canonical meta tags inside the HTML 1. Direct Browser Inspection1. Go to https://www.ory.sh/docs/account-experience
2. Right-click → "View Page Source" (I believe this shows server-rendered HTML that SEO crawlers see)
3. Search for "canonical"
4. Result: `<link rel="canonical" href="https://www.ory.sh/docs/account-experience/">` (with trailing slash)
# Note: DevTools shows the canonical WITHOUT trailing slash because client-side JavaScript modifies it after page load(I think from vercel's config of "trailingSlash: false"), but SEO crawlers don't see this change. 2. Command Line Check# Get the server HTML that search engines see
curl -s https://www.ory.sh/docs/account-experience | grep -i canonical
# Result: <link rel="canonical" href="https://www.ory.sh/docs/account-experience/"> The mismatch:
The mismatch is showing up in the Ahrefs Audit: Thanks for providing more info about categories. And yes, I totally agree and have removed the manual troubleshooting index page so that it can be generated from the sidebar config. Looks like there was a trailing slash at |
Oh I see, that makes much more sense to me now! why the heck is docusaurus doing this 🤔 Is it only on those pages you edited here or on all of the pages? |
@aeneasr Yeah seems to be a weird problem with docusaurus - https://stackoverflow.com/questions/78508730/how-to-correct-a-docusaurus-generated-canonical-url-that-points-to-a-redirect Yup, it's only happening on the pages I edited. It seems to only happen on @vinckr I have added a section that explains the canonicalUrl component in the README. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Almost there
@aeneasr Thanks for catching those! I've made the appropriate updates. Note on quote consistency: I noticed that after wrapping the CanonicalUrl imports in |
Yes, it‘s unfortunately the case but OK! |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Awesome! Could you also add to the readme an instruction for this pattern so any future contributors know what to do? :)
Summary
This PR implements SEO improvements and fixes duplicate content issues by addressing canonical URLs, trailing slashes, and troubleshooting page conflicts.
Key Changes:
trailingSlash: false
to Docusaurus config to ensure consistent canonical URLs without trailing slashes across/docs/
prefix (e.g.,[When to use OAuth2](/docs/hydra/concepts/before-oauth2)
) to ensure correct resolution whentrailingSlash: false
/troubleshooting
index and redirecting to the auto-generated/category/troubleshooting/
pageThis addresses issues where search engines were finding duplicate content and inconsistent canonical URLs, improving overall SEO performance.
Related Issue or Design Document
SEO optimization - canonical tag updates #2317
Checklist
If this pull request addresses a security vulnerability,
I confirm that I got approval (please contact [email protected]) from the maintainers to push the changes.
Further comments
Technical Details:
Trailing Slash Fix:
trailingSlash: false
ensures consistency across environments/docs/
prefix to ensure proper resolutionTroubleshooting Duplicate Content:
/troubleshooting
(manual index) and/category/troubleshooting/
(auto-generated) serving similar content/troubleshooting
→/category/troubleshooting/
to consolidate to one canonical pageTesting Instructions:
Before the fix:
npm run build
/oauth2-oidc
in the build directory<link rel="canonical" href="https://www.ory.sh/docs/oauth2-oidc/">
After the fix:
npm run build
/oauth2-oidc
in the build directory<link rel="canonical" href="https://www.ory.sh/docs/oauth2-oidc">
Update: Pivoted Approach
Previous Approach (Abandoned):
Initially attempted to set
trailingSlash: false
in Docusaurus config, but this broke hundreds of relative links throughout the documentation.Current Approach (Implemented):
Implemented a fix using a reusable
CanonicalUrl
component that: