Migrating from 3.0.0 to 3.1.1 result in "found broken links"

[axel7083]

Have you read the Contributing Guidelines on issues?

• I have read the Contributing Guidelines on issues.

Prerequisites

• I'm using the latest version of Docusaurus.
• I have tried the npm run clear or yarn clear command.
• I have tried rm -rf node_modules yarn.lock package-lock.json and re-installing packages.
• I have tried creating a repro with https://new.docusaurus.io.
• I have read the console error message carefully (if applicable).

Description

We are using the @docusaurus/plugin-client-redirects plugins, and it seems that when migrating all docusaurus elements to 3.1.1 some redirects are not made properly leading to docusaurus raising an error for broken links.

Reproducible demo

No response

Steps to reproduce

tests with 3.1.1

1. checkout the https://github.com/axel7083/podman-desktop/tree/deps/docusaurus-3-1-1 branch
2. cd to website
3. yarn install
4. yarn run build

tests with 3.0.0
Repeat the previous step with any commit prior to containers/podman-desktop@a8f5a93 (e.g. containers/podman-desktop@8a823fe)

Expected behavior

I am expected the build to be successful, as it is when using 3.0.0.

Actual behavior

Error: Unable to build website for locale en.
    at tryToBuildLocale (C:\Users\axels\Documents\github\redhat\podman-desktop\node_modules\@docusaurus\core\lib\commands\build.js:55:19)
    at async mapAsyncSequential (C:\Users\axels\Documents\github\redhat\podman-desktop\node_modules\@docusaurus\utils\lib\jsUtils.js:44:24)
    at async Command.build (C:\Users\axels\Documents\github\redhat\podman-desktop\node_modules\@docusaurus\core\lib\commands\build.js:82:21) {
  [cause]: Error: Docusaurus found broken links!

  Please check the pages of your site in the list below, and make sure you don't reference any path that does not exist.
  Note: it's possible to ignore broken links with the 'onBrokenLinks' Docusaurus configuration, and let the build pass.

  Exhaustive list of all broken links found:
  - Broken link on source page path = /docs/compose/running-compose:
     -> linking to /docs/onboarding-for-containers/installing-podman
  - Broken link on source page path = /docs/containers:
     -> linking to /docs/containers/registries/authenticating-to-a-preconfigured-registry
     -> linking to /docs/containers/registries/insecure-registry
  - Broken link on source page path = /docs/proxy/using-a-proxy:
     -> linking to /docs/compose/compose-spec

• /docs/onboarding-for-containers/installing-podman must be redirected to /docs/podman/installing (installing.md exists)
• /docs/containers/registries/authenticating-to-a-preconfigured-registry to /docs/containers/registries (registries is a folder with an index.md in it)
• /docs/compose/compose-spec to /docs/compose (compose is a folder with an index.md in it)

Your environment

• Public source code: https://github.com/axel7083/podman-desktop/tree/deps/docusaurus-3-1-1
• Public site URL: https://podman-desktop.io/
• Docusaurus version used: 3.0.0 and 3.1.1
• Environment name and version (e.g. Chrome 89, Node.js 16.4): Brave, NodeJS 18.17.1
• Operating system and version (e.g. Ubuntu 20.04.2 LTS): Windows 11

Self-service

• I'd be willing to fix this bug myself.

[OzakIOne]

Hi, we introduced a broken link detector feature in Docusaurus 3.1, these errors indicates broken links that links to non existent pages which needs to be updated, I saw that you fixed links in your commits and now the build is working

[axel7083]

Hi, we introduced a broken link detector feature in Docusaurus 3.1, these errors indicates broken links that links to non existent pages which needs to be updated, I saw that you fixed links in your commits and now the build is working

@OzakIOne Thanks for your answer and time, sadly I did not fixed it, I work around it.

From the documentation an anchor broken dectector was introduced in 3.1. The links were not broken, as the plugin redirect was suppose to take care of them.

From the changelog

For 3.1.1

🐛 Bug Fix

• fix(core): broken links optimization behaves differently than non-optimized logic #9791 fix(core): broken links optimization behaves differently than non-optimized logic (@slorber)
• fix(core): various broken anchor link fixes #9732 fix(core): various broken anchor link fixes (@slorber)

🏃‍♀️ Performance

• perf(core): optimize broken links checker #9778 perf(core): optimize broken links checker (@slorber)

For 3.1.0

🚀 New Feature

• feat(core): make broken link checker detect broken anchors - add onBrokenAnchors config #9528 feat(core): make broken link checker detect broken anchors - add onBrokenAnchors config (@OzakIOne)

Therefore, no breaking change notice, or different behavior was expected from 3.0.0. Therefore a regression has been introduced

[slorber]

@axel7083 there's a behavior change indeed, but we consider it as a bugfix instead of a breaking change.

You have broken links on your site. v3.0 simply did not report those properly, and v3.1 now report those.

See the problem in action on this prod page:
https://podman-desktop.io/docs/compose/running-compose

CleanShot.2024-02-01.at.12.43.32.mp4

Note: this page redirect exists (because it is created by the redirect plugin):
https://podman-desktop.io/docs/onboarding-for-containers/installing-podman

But it is not part of the app SPA routes so the redirect only happens when you open/refresh that URL, but shows a 404 when we navigate to it with the @docusaurus/Link component.

If you want to link to pages that are "outside" Docusaurus routing (ie html files generated by the redirect plugin), you should tell the link component to do so. For that we have a pathname:// protocol you can use on Markdown links.

---

In my opinion:

• You should prefer server-side redirects
• You should refactor your links to target the final destination page instead of redirect pages

[axel7083]

@slorber thanks you for your time and those advice, we will work on it on our side to try migrating to 3.1.1, thanks you again for the explanations and details !

[slorber]

👍 np

FYI we could enhance the system so that the redirect plugin routes can be navigated with @docusaurus/Link, by creating actual SPA redirect routes but I'd prefer not to for many reasons:

• This will be much slower to build than how we currently create the lightweight html redirect files, part of our std static generation pipeline
• This would be a React Router <Redirect/> component, and would require hydrating the redirect page with React before performing the client-side redirect, which would be delayed

For these reasons, we'd prefer to keep the system as is.