Stop the MCP doc sync reintroducing /en/-prefixed links - #189
Merged
Conversation
rewrite_internal_links() mapped the source repo's /docs/<file>.md targets to /en/bitrise-platform/... . 51f565b stripped that prefix repo-wide and CLAUDE.md now documents the convention, but the sync script was missed by that sweep — so every run silently undid it for these eight pages. Internal links must be bare absolute paths: each locale has its own baseUrl (i18n.localeConfigs in docusaurus.config.ts), which Docusaurus prepends at render time. A hardcoded /en/ resolves to /ja/en/... under any other locale, which doesn't exist. Only this one function was affected — SLUG_BASE and build_frontmatter() already emit bare paths, so page slugs were never wrong. The checked-in pages are already correct (51f565b fixed the content), so the sync now produces no diff against them. Verified: a run over a clean tree reports all seven install pages unchanged, and a second run writes nothing. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Picked up by the sync run in the previous commit, and unrelated to it: upstream documented a new `stack` parameter on trigger_bitrise_build, which overrides the workflow's meta.bitrise.io.stack for a single build. Generated by scripts/sync_mcp_docs.py — not hand-edited. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
matenadasdi
requested review from
aorcsik,
ilanazholobovsky and
zoltan-baba
as code owners
August 18, 2026 14:20
zoltan-baba
approved these changes
Aug 18, 2026
matenadasdi
added a commit
that referenced
this pull request
Aug 18, 2026
Brings in the infrastructure that was split out of this PR and has since merged — #188 (the <NT> component, the 83 .md -> .mdx renames, the check-links-source.js anchor fix, the patch-api-info.js duplicate-label fix) and #189 (the MCP sync /en/ fix) — plus #187's docusaurus-plugin-llms bump. The overlapping work is identical on both sides, so it resolves without conflict. What remains unique to this branch is the translation pipeline, the localization glossary and guides, the i18n/ja content, and the locale switcher. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
6 tasks
ilanazholobovsky
added a commit
that referenced
this pull request
Aug 19, 2026
The previous commit set `info_path` to `en/...`. That fixes the en build but breaks the ja one, and it contradicts the convention #189 established. The theme renders the value through Docusaurus's <Link>: const infoAuthPath = `/${props.infoPath}#authentication`; <Link to={infoAuthPath}>...</Link> <Link> prepends the active locale's baseUrl unless the path already starts with it. So `en/...` renders as /en/... on the en build (correct, since it already carries the prefix) but as /ja/en/... on the ja build, which doesn't exist. Verified on the deploy preview: /ja/bitrise-api/api-reference/activity-list -> Authentication href /ja/en/bitrise-api/api-reference/bitrise-api -> 404 That is the exact failure mode sync_mcp_docs.py's rewrite_internal_links warns about, and the reason #189 stripped hardcoded /en/ from synced links. A bare route path is correct for every locale, because <Link> supplies the prefix. Both info pages exist under both locales today (the ja build falls back to the untranslated source), verified on the same preview: /en/bitrise-api/api-reference/bitrise-api -> 200 /ja/bitrise-api/api-reference/bitrise-api -> 200 /en/bitrise-rde-api/.../bitrise-remote-dev-environments-api -> 200 /ja/bitrise-rde-api/.../bitrise-remote-dev-environments-api -> 200 Also corrects the root-cause note in the script's header. The plugin does have logic to turn outputDir into a route, but it is guarded (plugin src/index.ts, v5.0.2): let infoBasePath = `${outputDir}/${item.infoId}`; if (docRouteBasePath) { ...rebuild from docRouteBasePath... } `docs.routeBasePath` is '' here, which is falsy, so the guard never fires and the raw filesystem path is written. This was latent until routeBasePath changed from 'en' to '' — which is why the value was correct before the change and wrong after the next regeneration. - EN_ROUTE_PREFIX -> ROUTE_BASE_PATH, mirroring docs.routeBasePath - Regenerate the 164 *.api.mdx via the script (one line each)
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.
rewrite_internal_links()inscripts/sync_mcp_docs.pymapped the source repo's/docs/<file>.mdtargets to/en/bitrise-platform/.... 51f565b stripped that prefix repo-wide and CLAUDE.md now documents the convention, but the sync script was missed by the sweep — so every run silently undid it for these eight pages.Internal links must be bare absolute paths: each locale has its own
baseUrl(i18n.localeConfigsindocusaurus.config.ts), which Docusaurus prepends at render time. A hardcoded/en/resolves to/ja/en/...under any other locale, which doesn't exist.Only this one function was affected —
SLUG_BASEandbuild_frontmatter()already emit bare paths, so page slugs were never wrong.Stacked on #188
Based on
ja-infra-prep, notmain— merge #188 first. These eight pages are.mdxonly on that branch, and #188 also carries the.mdxdestination fix without which a sync run produces stray.mdduplicates.Verified
stackparameter ontrigger_bitrise_build.node scripts/check-links-source.js— clean, 631 files.npm run build— green for both locales, zero broken-link warnings.Toolslink frominstall-claudenow renders as/en/bitrise-platform/ai/bitrise-mcp/toolsin theenbuild and/ja/bitrise-platform/ai/bitrise-mcp/toolsin thejabuild. No/ja/en/anywhere in thejaoutput — which is the bug this fixes.#section), external.mdURLs (untouched), and already-bare paths (untouched).Found while checking, not fixed here
descriptionfrontmatter —build_frontmatter()never emits the field, so they fall back to the generic site tagline in social preview cards. A hand edit wouldn't survive a sync; it needs a stem → description map in the script. Left for its own PR since it's content copy, not a script bugfix.src/html/portal.htmlstill contains/en/….htmllinks. It isn't referenced anywhere and isn't in the build output — a leftover from the pre-Docusaurus portal — so those are dead weight rather than a live bug.🤖 Generated with Claude Code