fix(links): drop the hardcoded baseUrl and repair stale anchors by thetaPC · Pull Request #4736 · ionic-team/ionic-docs

thetaPC · 2026-09-15T17:37:03Z

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 · 2026-09-15T17:37:09Z

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

Project	Deployment	Actions	Updated
ionic-docs	Ready	Preview	Sep 16, 2026 8:23pm UTC

thetaPC · 2026-09-15T22:15:02Z

 :::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.


The section only existed in v5.

I removed these in my PR also: link

thetaPC · 2026-09-15T22:15:18Z

 :::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.


The section only existed in v5.

thetaPC · 2026-09-15T22:18:13Z

 ```

-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).


That section only existed in v5 and v6.

thetaPC · 2026-09-15T22:18:29Z

 ```

-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).


That section only existed in v5 and v6.

thetaPC · 2026-09-15T23:23:27Z


 :::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.


The section only existed in v5.

thetaPC · 2026-09-15T23:24:15Z

 ```

-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).


That section only existed in v5 and v6.

ShaneK

Looks good to me, great work! English comes out at 0 broken links and 0 broken anchors in a local build, down from 7 and 40 on main, and the couple of things I left are nits. 🚀

ShaneK · 2026-09-16T17:58:44Z

          "type": "link",
          "label": "Responsive Grid",
-          "href": "/docs/api/grid"
+          "href": "/api/grid"


Suggested change

"href": "/api/grid"

"href": "/v8/api/grid"

This renders as /docs/api/grid, so the v8 sidebar sends people to the v9 docs. Pre-existing rather than something you introduced, but the line's already open here, and the v6/v7 sidebars have the same entry.

ShaneK · 2026-09-16T18:00:39Z

    let docs = prop.docs;
    if (isVirtual) {
-      docs = `${docs}\n\nThis is a [virtual property](/docs/core-concepts/fundamentals#virtual-properties) that is set once during initialization and will not update if you change its value after the initial render.`;
+      docs = `${docs}\n\nThis is a [virtual property](/core-concepts/fundamentals#virtual-properties) that is set once during initialization and will not update if you change its value after the initial render.`;


Under ja this resolves to the right page but the Japanese fundamentals heading has no explicit id, so it comes out as 103 broken anchors (they were hard 404s before this PR, so still a win). Adding {/* #virtual-properties */} to that heading in the translation/jp copy clears all 103, matching what's already there for #adaptive-styling.

Agreed. The jp heading is ### 仮想プロパティ, so it needs {/* #virtual-properties */} the same way #adaptive-styling already does two headings up.

It points at a bigger question though: 1,072 translated ja headings have no pinned id, so their anchors can't match English. I want to look into whether the standard should be that headings in docs/ carry explicit ids.

ShaneK · 2026-09-16T18:02:03Z

    <p>A modern, open source native runtime built and maintained by the Ionic team and the Capacitor community. Our recommended native solution.</p>
  </DocsCard>
-  <DocsCard header="Cordova plugins" img="/img/native/cordova@2x.png" href="/native/community">
+  <DocsCard header="Cordova plugins" img="/img/native/cordova@2x.png" href="/v5/native/community">


Any reason this one keeps an in-site path rather than the archive URL from versionsArchived.json like the others here? It does work and the file's in an unbuilt tree anyway, so purely consistency - up to you!

The archive URLs elsewhere are for targets that don't exist in any built tree. Here the target is in the same tree, native-community.mdx with slug: /native/community, so there's a real page to point at.

Kept it internal because the archive URL is never the better of the two. If v5 were ever unarchived it would send people to a frozen snapshot instead of the page that just got built, and it's another hardcoded deploy URL we'd have to remember to update if that archive ever moves, which nothing in the build would catch.

…inks

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

7d9824c

thetaPC commented Sep 15, 2026

View reviewed changes

fix(links): repair broken links and anchors in every docs version

1c81b80

vercel Bot deployed to Preview September 15, 2026 22:24 View deployment

fix(links): repair broken links and anchors in every docs version

2091890

vercel Bot deployed to Preview September 15, 2026 23:06 View deployment

thetaPC commented Sep 15, 2026

View reviewed changes

fix(links): repair broken links and anchors in every docs version

37bcd49

vercel Bot deployed to Preview September 15, 2026 23:27 View deployment

thetaPC marked this pull request as ready for review September 15, 2026 23:51

thetaPC requested a review from a team as a code owner September 15, 2026 23:51

thetaPC requested a review from ShaneK September 15, 2026 23:52

ShaneK approved these changes Sep 16, 2026

View reviewed changes

fix(links): point the versioned grid sidebar links at their own version

d33c6c5

vercel Bot deployed to Preview September 16, 2026 18:34 View deployment

Merge branch 'main' of github.com:ionic-team/ionic-docs into broken-l…

41fd7dc

…inks

vercel Bot deployed to Preview September 16, 2026 20:23 View deployment

thetaPC merged commit 90892bc into main Sep 16, 2026
7 checks passed

thetaPC deleted the broken-links branch September 16, 2026 20:51

thetaPC mentioned this pull request Sep 16, 2026

fix(links): repair the broken links on the Japanese site #4739

Open

2 tasks

Uh oh!

Conversation

thetaPC commented Sep 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What is the current behavior?

What is the new behavior?

Does this introduce a breaking change?

Other information

Uh oh!

vercel Bot commented Sep 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

brandyscarney Sep 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ShaneK left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

thetaPC commented Sep 15, 2026 •

edited

Loading

vercel Bot commented Sep 15, 2026 •

edited

Loading

brandyscarney Sep 16, 2026 •

edited

Loading