fix: remove staging-fork special case from DOCS_BASE_URL; improve README#67
Merged
planetf1 merged 3 commits intoJun 10, 2026
Merged
Conversation
The planetf1/granite-docs hardcode in the DOCS_BASE_URL condition was added temporarily to validate the Akamai staging path (ibm-granite#63). That staging target is confirmed working, so the special case is no longer needed and actively breaks GitHub Pages previews on that fork — assets 404 because the base URL doesn't match the /repo-name/ path GitHub Pages serves forks at. Restores two-tier behaviour: - ibm-granite/docs → /granite/docs/ (IBM.com public path, proxied by Akamai) - any fork → /{repo-name}/granite/docs/ (GitHub Pages preview path) Also adds a repository layout reference to README and tightens up the contributing guide with optional frontmatter fields and the CodeGroup component. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
DOCS_SITE_URL was always github.io which caused canonical URLs, og:url, og:image, and sitemap entries to point to ibm-granite.github.io instead of www.ibm.com. This breaks SEO — search engines would index the GitHub Pages URL as canonical rather than the IBM.com URL. Upstream now gets https://www.ibm.com; forks keep their github.io URL which is correct for GitHub Pages preview links. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
robots.txt was missing — requests to /granite/docs/robots.txt were redirecting to the home page. Adds a static robots.txt that allows crawling and points to the canonical sitemap URL. The /search page is a Docusaurus UI page with no static content; it should not appear in the sitemap. Adds ignorePatterns to the sitemap plugin config to exclude it. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
serjikibm
approved these changes
Jun 10, 2026
serjikibm
left a comment
serjikibm
left a comment
Collaborator
There was a problem hiding this comment.
Reviewed the PR, also got AI review on it, no additional comments. All looks good. Minor nit (nothing needed changing now), robots.txt will use www.ibm.com even in staging from forks, etc. something to consider when we have the staging strategy.
Collaborator
Author
|
Thanks @serjikibm. Opened #71 to address |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR fixes several SEO issues found during a site audit of
wwwstage.ibm.com/granite/docs(the Docusaurus staging site). These need to be resolved before the production cutover from Mintlify —www.ibm.com/granite/docscurrently still serves the old Mintlify site.Fix: canonical URLs, og:image, and sitemap pointing to wrong domain
DOCS_SITE_URLwas alwayshttps://ibm-granite.github.io, so every built page emits:<link rel="canonical">andog:urlpointing toibm-granite.github.ioinstead ofwww.ibm.com— Google would treat the GitHub Pages URL as canonical, not the IBM.com URLog:imageresolves to a 404 onibm-granite.github.io(that domain doesn't serve the docs at that path) — social previews would be broken on every pagesitemap.xmllists all URLs underibm-granite.github.ioFixed by setting
DOCS_SITE_URLtohttps://www.ibm.comfor the upstream build. Forks keephttps://{owner}.github.io, which combined with the fork'sDOCS_BASE_URLgives the correct GitHub Pages preview URL.Fix: missing robots.txt
GET /granite/docs/robots.txtwas falling through to a redirect to the home page. Adds a staticrobots.txtthat allows crawling and points to the canonical sitemap URL onwww.ibm.com.Fix: /search page in sitemap
The Docusaurus search page has no static content and should not appear in the sitemap. Adds
ignorePatterns: ['/search']to the sitemap plugin config.Cleanup: remove stale staging-fork hardcode
The
planetf1/granite-docsspecial case inDOCS_BASE_URLwas added temporarily in #63 to validate the Akamai staging path, which is now confirmed working. Removes it and restores clean two-tier logic: upstream gets/granite/docs/; all forks get/{repo-name}/granite/docs/.Docs: README improvements
Adds a repository layout reference section and tightens up the contributing guide (optional frontmatter fields,
<CodeGroup>component).Verification
On wwwstage.ibm.com after CI runs:
<link rel="canonical">on any page points towww.ibm.com/granite/docs/...og:imageURL iswww.ibm.com/granite/docs/images/hero-light.pngGET /granite/docs/robots.txtreturns the robots file (not a redirect)GET /granite/docs/sitemap.xml— all URLs usewww.ibm.com, no/searchentryAfter production cutover:
www.ibm.com🤖 Generated with Claude Code