Skip to content

fix(links): drop the hardcoded baseUrl and repair stale anchors - #4736

Open
thetaPC wants to merge 4 commits into
mainfrom
broken-links
Open

thetaPC wants to merge 4 commits into
mainfrom
broken-links

Conversation

@thetaPC

@thetaPC thetaPC commented Sep 15, 2026

Copy link
Copy Markdown
Contributor

Issue URL: internal

What is the current behavior?

The Japanese site renders 724 broken links. English renders 21, plus 50 broken anchors nobody had noticed. The archived v5, v6 and v7 docs carry the same defects and have never been checked, because they are not built.

Nearly every broken link is one defect: links hardcode the /docs baseUrl. Docusaurus prepends the baseUrl of the locale being built, and the Japanese one is /docs/ja/, so the prefix doubles into /docs/ja/docs/theming/basics. English hides it, because a value that already starts with its own baseUrl is passed through untouched.

The anchors are unrelated: fragments pointing at headings renamed years ago. #style-placement and #optimizing-your-build were v5 sections, dead through four majors.

What is the new behavior?

English is at 0 broken links and 0 broken anchors. Japanese links drop 724 to 152, with nothing left that originates in an English source file. Built with all five versions, the archived trees come out clean apart from five links noted below.

  • Markdown links use root absolute paths carrying the target's extension, /api/toolbar.mdx. The extension matters: the resolver only fires on .md and .mdx, and it searches the localized content path first, which makes this the one style that is both locale correct and version correct.
  • JSX href attributes take the same path without an extension, since no resolver runs there and the value goes straight to Link.
  • One sidebar link is rendered into every docs page and accounted for 261 by itself.
  • The API plugin now drops the baseUrl as it renders the fetched JSON. Those links reach us from three separately generated sources, so an upstream PR alone would have missed v8 and the Japanese API data.
  • Anchors were resolved against the ids that actually exist in the built HTML, per version. A section removed in one version often still exists in an older one, so only the genuinely stale links changed.
  • Links pointing into archived versions now use the frozen archive URLs, since those versions are not built.

Does this introduce a breaking change?

  • Yes
  • No

Other information

60 anchors will still be reported, and all 60 work. Docusaurus collects anchors only from components that call collectAnchor, so a raw <section id="cli"> written straight into MDX is invisible to it. The v5 and v6 glossaries are built that way. These should not be "fixed".

5 links stay broken in v5. They come from @ionic/docs@5, which uses a relative link style dropped after v5, and exist only in a build-time partial, so there is no file to edit. v5 is not built.

Japanese broken anchors rise 66 to 148. That is not new breakage: links that used to 404 now land on the correct translated page, whose heading slug is Japanese, so the fragment misses instead.

ja never builds in PR previews, so none of this is visible from the preview link. I verified with a local two-locale build, and again with v5, v6 and v7 temporarily added to versions.json.

Everything still broken lives in translation/jp. The plan is this PR, then a normal main to jp sync, which carries most of the prose fixes as conflicts to resolve, then a small jp PR for the rest. 103 of the Japanese leftovers are a single missing heading id in the jp fundamentals.mdx, on a heading whose slug is Japanese.

@vercel

vercel Bot commented Sep 15, 2026

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
ionic-docs Ready Ready Preview Sep 15, 2026 11:27pm UTC

Request Review

:::note

If you are building an Ionic Angular app, the styles need to be added to a global stylesheet file. Read [Style Placement](#style-placement) in the Angular section below for more information.
If you are building an Ionic Angular app, the styles need to be added to a global stylesheet file.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The section only existed in v5.

Comment thread docs/api/modal.mdx
:::note

If you are building an Ionic Angular app, the styles need to be added to a global stylesheet file. Read [Style Placement](#style-placement) in the Angular section below for more information.
If you are building an Ionic Angular app, the styles need to be added to a global stylesheet file.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The section only existed in v5.

```

This error is an error code from Xcode that can be caused by provisioning issues or outdated cordova dependencies. To fix this error first make sure a provisioning profile has been generated using the above instructions and then try to [run the app from Xcode](../developing/ios.mdx#running-with-xcode).
This error is an error code from Xcode that can be caused by provisioning issues or outdated cordova dependencies. To fix this error first make sure a provisioning profile has been generated using the above instructions and then try to [run the app from Xcode](/developing/ios.mdx).

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That section only existed in v5 and v6.

```

This error is an error code from Xcode that can be caused by provisioning issues or outdated cordova dependencies. To fix this error first make sure a provisioning profile has been generated using the above instructions and then try to [run the app from Xcode](../developing/ios.mdx#running-with-xcode).
This error is an error code from Xcode that can be caused by provisioning issues or outdated cordova dependencies. To fix this error first make sure a provisioning profile has been generated using the above instructions and then try to [run the app from Xcode](/developing/ios.mdx).

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That section only existed in v5 and v6.


:::note
If you are building an Ionic Angular app, the styles need to be added to a global stylesheet file. Read [Style Placement](#style-placement) in the Angular section below for more information.
If you are building an Ionic Angular app, the styles need to be added to a global stylesheet file.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The section only existed in v5.

```

This error is an error code from Xcode that can be caused by provisioning issues or outdated cordova dependencies. To fix this error first make sure a provisioning profile has been generated using the above instructions and then try to [run the app from Xcode](../developing/ios.mdx#running-with-xcode).
This error is an error code from Xcode that can be caused by provisioning issues or outdated cordova dependencies. To fix this error first make sure a provisioning profile has been generated using the above instructions and then try to [run the app from Xcode](../developing/ios.mdx).

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That section only existed in v5 and v6.

@thetaPC
thetaPC marked this pull request as ready for review September 15, 2026 23:51
@thetaPC
thetaPC requested a review from a team as a code owner September 15, 2026 23:51
@thetaPC
thetaPC requested a review from ShaneK September 15, 2026 23:52
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant