You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@apisix.apache.org by "Yilialinn (via GitHub)" <gi...@apache.org> on 2026/05/13 07:36:42 UTC
[PR] fix: use absolute URLs for cross-workspace navigation links [apisix-website]
Yilialinn opened a new pull request, #2043:
URL: https://github.com/apache/apisix-website/pull/2043
## 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:
```
[06:48:20] Build website's all parts [failed]
[06:48:20] → Build failed for: doc
Error: Build failed for: doc
info Docusaurus found broken links!
```
**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 with `target='_parent'`).
### Changes Made
**config/navbar.js:**
- Learning Center: `/learning-center` → `https://apisix.apache.org/learning-center/`
- Blog: `/blog` → `https://apisix.apache.org/blog/`
- Case Studies: `/blog/tags/case-studies` → `https://apisix.apache.org/blog/tags/case-studies/`
- Downloads: `/downloads` → `https://apisix.apache.org/downloads/`
- Help: `/help` → `https://apisix.apache.org/help/`
- Team: `team` → `https://apisix.apache.org/team/`
- Showcase: `/showcase` → `https://apisix.apache.org/showcase/`
- PluginHub: `/plugins` → `https://apisix.apache.org/plugins/`
**doc/src/theme/Footer/index.tsx:**
- Blog: `/blog/` → `https://apisix.apache.org/blog/`
- Showcase: `/showcase` → `https://apisix.apache.org/showcase/`
- Plugin Hub: `/plugins` → `https://apisix.apache.org/plugins/`
**doc/src/theme/NotFound/index.tsx:**
- Homepage: `/` → `https://apisix.apache.org/`
## Why This Approach?
1. **Maintains broken link detection**: Keeps `onBrokenLinks: 'log'` so we still catch actual broken documentation links
2. **No user impact**: Links behave identically from the user's perspective
3. **Proper separation**: Respects workspace boundaries - cross-workspace navigation uses absolute URLs
4. **Future-proof**: If workspaces are ever deployed separately, links still work
## Testing
- [ ] Local build: `yarn workspace doc build` (should succeed)
- [ ] CI build should pass
- [ ] Verify navbar/footer links work correctly on deployed site
## Related
- Failed CI run: https://github.com/apache/apisix-website/actions/runs/25147485898
- This issue is unrelated to PR #2034 (April monthly report) which was successfully merged
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] fix: use absolute URLs for cross-workspace navigation links [apisix-website]
Posted by "Copilot (via GitHub)" <gi...@apache.org>.
Copilot commented on code in PR #2043:
URL: https://github.com/apache/apisix-website/pull/2043#discussion_r3232477824
##########
config/navbar.js:
##########
@@ -2,7 +2,7 @@ module.exports = [
{
label: 'Docs',
position: 'right',
- to: '/docs',
+ href: 'https://apisix.apache.org/docs/',
target: '_parent',
Review Comment:
The PR description’s root cause is broken links to routes that *don’t exist* in the `doc` workspace (e.g. `/blog`, `/downloads`, etc.). `/docs` is expected to exist in the doc workspace, so converting the primary Docs entry to an absolute production URL is likely unnecessary and can regress local/dev/staging behavior (always sends users to production) and forces a full page load instead of SPA navigation. Recommendation: keep `/docs` as an internal `to: '/docs'` link (and only convert truly cross-workspace routes to absolute URLs).
##########
config/navbar.js:
##########
@@ -47,43 +47,43 @@ module.exports = [
},
{
label: 'General',
- to: '/docs/general/join',
+ href: 'https://apisix.apache.org/docs/general/join/',
target: '_parent',
},
Review Comment:
This converts an in-docs page (`/docs/general/join/`) to an absolute production URL. If this page exists within the doc workspace, it shouldn’t be part of the broken-link problem and changing it to an external link harms local preview, environment parity (staging), and in-app navigation performance. Suggest reverting doc-owned routes under `/docs/...` back to internal `to: '/docs/...'` (keeping absolute URLs only for routes owned by `website`/`blog` workspaces).
##########
config/navbar.js:
##########
@@ -47,43 +47,43 @@ module.exports = [
},
{
label: 'General',
- to: '/docs/general/join',
+ href: 'https://apisix.apache.org/docs/general/join/',
target: '_parent',
},
],
},
{
- to: '/learning-center',
+ 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',
},
Review Comment:
The same absolute origin (`https://apisix.apache.org`) is repeated across multiple entries (and in other files touched by this PR). This increases the chance of inconsistent updates later (e.g., domain change, previews). Recommendation: extract a single base-URL constant in this module (e.g., `const APISIX_SITE = 'https://apisix.apache.org'`) and build `href` values from it, or use an environment/config-driven value where feasible so preview/staging deployments don’t hardcode production.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] fix: use absolute URLs for cross-workspace navigation links [apisix-website]
Posted by "Yilialinn (via GitHub)" <gi...@apache.org>.
Yilialinn closed pull request #2043: fix: use absolute URLs for cross-workspace navigation links
URL: https://github.com/apache/apisix-website/pull/2043
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] fix: use absolute URLs for cross-workspace navigation links [apisix-website]
Posted by "Yilialinn (via GitHub)" <gi...@apache.org>.
Yilialinn commented on PR #2043:
URL: https://github.com/apache/apisix-website/pull/2043#issuecomment-4458251962
The problem is resolved in https://github.com/apache/apisix/pull/13378
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] fix: use absolute URLs for cross-workspace navigation links [apisix-website]
Posted by "yzeng25 (via GitHub)" <gi...@apache.org>.
yzeng25 commented on PR #2043:
URL: https://github.com/apache/apisix-website/pull/2043#issuecomment-4438887760
How did relative paths work for previous pull requests and suddenly not working for this particular pull request?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org