docusaurus: yarn build error with "Docusaurus found broken links" after set baseUrl to "/docs/"

Have you 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

yarn build error with “Docusaurus found broken links” after set baseUrl to “/docs/”

Steps to reproduce

  1. init
npx create-docusaurus@latest docs classic
  1. build
cd docs 		
yarn build
...
[SUCCESS] Generated static files in build.
[INFO] Use `npm run serve` command to test your build locally.
Done in 69.04s.
PS D:\Document\github\docs>
  1. change baseUrl from ‘/’ to ‘/docs/’
# docusaurus.config.js
-   baseUrl: '/',
+  baseUrl: '/docs/',
  1. build
yarn build
...
[ERROR] Unable to build website for locale en.
[ERROR] 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.

It looks like some of the broken links we found appear in many pages of your site.
Maybe those broken links appear on all pages through your site layout?
We recommend that you check your theme configuration for such links (particularly, theme navbar and footer).
Frequent broken links are linking to:
- /docs/intro


Exhaustive list of all broken links found:

- On source page path = /docs/404.html:
   -> linking to /docs/intro
  1. check the links in files generated by build
<a class="button button--secondary button--lg" href="/docs/intro">Docusaurus Tutorial - 5min ⏱️</a>

Expected behavior

the links in files generated by build should be like this

<a class="button button--secondary button--lg" href="/docs/docs/intro">Docusaurus Tutorial - 5min ⏱️</a>

Actual behavior

link in document should be like ‘/docs/docs/intro’, but actually is ‘/docs/intro’

Your environment

Reproducible demo

No response

Self-service

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

About this issue

  • Original URL
  • State: open
  • Created 2 years ago
  • Reactions: 1
  • Comments: 20

Commits related to this issue

Most upvoted comments

  • I am truly sorry for not withdrawing the issue here after we fixed our issues (there was an actual problem with our links) which i could not figure out by myself at the time

  • When I found this issue i thought the problem might be similar (we recently upgraded to v2 that’s why I was looking to the problem outside of our repository)

  • We got our docs to be published here without any problems

  • Thank you for reaching out (and for your time) and again sorry for the inconvenience my comment might have caused.

@slorber

I solved it by using a different basePath other than /docs/, like /help/.

Then the conflict didn’t arise, and relative file pathing worked just fine.

@Arhell I believe this could be related to a subtle changes we made to how the doc slug is computed.

  • workflow/workflow.md => URL is now /workflow instead of /workflow/workflow
  • addon/addon.md => URL is now /workflow instead of /addon/addon

Broken links checking only happens on prod builds, and you have to carefully check the error message to debug such issues:

Exhaustive list of all broken links found:
- On source page path = /docs/next/end-user/traits/more:
   -> linking to ../../how-to/cli/addon/addon (resolved as: /docs/next/how-to/cli/addon/addon)
- On source page path = /docs/next/platform-engineers/policy/custom-policy:
   -> linking to ../workflow/workflow (resolved as: /docs/next/platform-engineers/workflow/workflow)
- On source page path = /docs/next/platform-engineers/traits/customize-trait:
   -> linking to ../workflow/workflow (resolved as: /docs/next/platform-engineers/workflow/workflow)

If the above message is not clear, can you help us improve it?

For example, this means that this doc page does not link properly to the addon page anymore:

The problematic markdown link is [install addons](../../how-to/cli/addon/addon), and should now be `install addons => note we recommend in our doc to link to docs with a relative file path (including .md extension): this makes the link insensitive to doc URL changes.

All this is not really related to the current issue. Can we move this to a separate discussion if you need more help?

Thank you, with the help of tests (manual) I did it.