fix: use absolute URLs for cross-workspace navigation links#2043
Closed
Yilialinn wants to merge 2 commits into
Closed
fix: use absolute URLs for cross-workspace navigation links#2043Yilialinn wants to merge 2 commits into
Yilialinn wants to merge 2 commits into
Conversation
Fix doc workspace build failures by converting relative links to absolute URLs for paths that exist in the website workspace but not in the doc workspace. Changes: - config/navbar.js: Convert blog, learning-center, downloads, help, team, showcase, and plugins links from relative paths to absolute URLs - doc/src/theme/Footer/index.tsx: Convert blog, showcase, and plugins links to absolute URLs - doc/src/theme/NotFound/index.tsx: Convert homepage link to absolute URL This prevents Docusaurus from treating cross-workspace links as internal broken links during isolated doc workspace builds, while maintaining the same user experience (links still work correctly with target='_parent'). Fixes build failures seen in CI runs starting from May 13, 2026. Related: https://github.com/apache/apisix-website/actions/runs/25147485898
Add missing fixes for: - /docs/ (navbar dropdown parent link) - /docs/general/join/ (appears twice in navbar) - /docs/general/code-samples/ - /docs/general/events/ These paths exist in the website workspace but not in the doc workspace, causing the same broken link validation failures.
Contributor
There was a problem hiding this comment.
Pull request overview
Note
Copilot was unable to run its full agentic suite in this review.
Fixes Docusaurus “broken link” build failures in the doc workspace by changing cross-workspace navigation links (navbar/footer/404) from internal relative paths to absolute https://apisix.apache.org/... URLs so they aren’t validated as in-workspace routes during the doc build.
Changes:
- Convert cross-workspace navbar items from
to: '/...'tohref: 'https://apisix.apache.org/.../' - Convert footer links to absolute URLs for website-only routes
- Update the doc workspace 404 page “home page” link to the absolute homepage URL
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
doc/src/theme/NotFound/index.tsx |
Updates the “home page” link on 404 to point to the website root via absolute URL. |
doc/src/theme/Footer/index.tsx |
Converts footer items that target website-only pages to absolute URLs to avoid doc-workspace link validation failures. |
config/navbar.js |
Converts navbar items to absolute URLs to avoid doc-workspace link validation failures for routes owned by other workspaces. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
2
to
6
| { | ||
| label: 'Docs', | ||
| position: 'right', | ||
| to: '/docs', | ||
| href: 'https://apisix.apache.org/docs/', | ||
| target: '_parent', |
Comment on lines
49
to
52
| label: 'General', | ||
| to: '/docs/general/join', | ||
| href: 'https://apisix.apache.org/docs/general/join/', | ||
| target: '_parent', | ||
| }, |
Comment on lines
+56
to
66
| href: 'https://apisix.apache.org/learning-center/', | ||
| label: 'Learning Center', | ||
| position: 'right', | ||
| target: '_parent', | ||
| }, | ||
| { | ||
| to: '/blog', | ||
| href: 'https://apisix.apache.org/blog/', | ||
| label: 'Blog', | ||
| position: 'right', | ||
| target: '_parent', | ||
| }, |
Contributor
|
How did relative paths work for previous pull requests and suddenly not working for this particular pull request? |
Contributor
Author
|
The problem is resolved in apache/apisix#13378 |
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
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
Fix doc workspace build failures by converting relative links to absolute URLs for paths that exist in the website workspace but not in the doc workspace.
Problem
The doc build has been failing since May 13, 2026 with:
Root cause: The apisix-website repository uses separate Docusaurus workspaces (
doc,website,blog) that build independently and are then assembled. During the doc workspace build, Docusaurus validates all links in the navbar and footer. Links pointing to paths that exist in the website workspace (/,/blog,/learning-center,/downloads,/help,/team,/showcase,/plugins) fail validation because these paths don't exist in the doc workspace.Solution
Convert cross-workspace navigation links from relative paths to absolute URLs using
https://apisix.apache.org/. This prevents Docusaurus from validating them as internal links while maintaining the same user experience (links work correctly withtarget='_parent').Changes Made
config/navbar.js:
/learning-center→https://apisix.apache.org/learning-center//blog→https://apisix.apache.org/blog//blog/tags/case-studies→https://apisix.apache.org/blog/tags/case-studies//downloads→https://apisix.apache.org/downloads//help→https://apisix.apache.org/help/team→https://apisix.apache.org/team//showcase→https://apisix.apache.org/showcase//plugins→https://apisix.apache.org/plugins/doc/src/theme/Footer/index.tsx:
/blog/→https://apisix.apache.org/blog//showcase→https://apisix.apache.org/showcase//plugins→https://apisix.apache.org/plugins/doc/src/theme/NotFound/index.tsx:
/→https://apisix.apache.org/Why This Approach?
onBrokenLinks: 'log'so we still catch actual broken documentation linksTesting
yarn workspace doc build(should succeed)Related