Docusaurus: `Error: Broken links found!` facing on docusaurus build

[bhaskarhc]

🐛 Bug Report

• Recent build are getting failed with an below error message ,

ValidationError: themeConfig.navbar.links has been renamed as themeConfig.navbar.items

• Replaced links with items on docusaurus.config.js
• Again all sidebar links getting broke on docusaurus build

Build Logs

Error: Broken links found!

- Page path = /docs/dir1***/dir-2***/dir-3***:
   -> link to /<readme-file>
   -> link to /<readme-file>
   -> link to /<readme-file>
   -> link to /<readme-file>
   -> link to /<readme-file>

Note: it's possible to ignore broken links with the 'onBrokenLinks' Docusaurus configuration.

[slorber]

@bhaskarhc broken links detection is new, and as it's shawn in the error message you can simply disable it if it's annoying to you.

However if you feel like it reports broken links while it shouldn't, I'd be interested to have more informations.

Do you have a public site, a public repo, a PR migrating your site to alpha.59?

If not, can you give us the real file structure of your site, the urls of docs that actually exist, and the navbar.items config content.

From the data you gave us, I can't check anything.

[bhaskarhc]

@slorber PTAL of code repo https://github.com/mayadata-io/oep-e2e/tree/master/testplan

[slorber]

@bhaskarhc this site is not alpha 59, can you provide me the site that produces the broken links

Also it would help if I could see the existing site hosted somewhere online

From your repo, I see 3 nav items, which one is being reported as broken?

Error: Broken links found!

- Page path = /docs/dir1***/dir-2***/dir-3***:
   -> link to /<readme-file>
   -> link to /<readme-file>
   -> link to /<readme-file>
   -> link to /<readme-file>
   -> link to /<readme-file>

Note: it's possible to ignore broken links with the 'onBrokenLinks' Docusaurus configuration.

Please give me the non-obfuscated output, I need to see the real content of this error

[bhaskarhc]

By seeing the Failed build logs got that links key need to Replace with items in docusaurus config .
, made replace chnages links with items in docusaurus.config and pushed [ commit changes ] (https://github.com/mayadata-io/oep-e2e/pull/828) .
@slorber Whatever changes did that build is also got failed with error message of Error: Broken links found!, build logs can see here https://travis-ci.com/github/mayadata-io/oep-e2e/builds/177425701 .

[bhaskarhc]

@slorber
site hosted domain https://e2e.mayadata.io/docs/getstarted

[slorber]

@bhaskarhc thanks. I now have proper informations to reproduce this bug:

Page /docs/director/authentication/authentication contains a link to an existing doc in the same dir: [TCID-DIR-AUTH-LOCAL-ADMIN](TCID-DIR-AUTH-LOCAL-ADMIN)

But this link is reported as broken:

- Page path = /docs/director/authentication/authentication:
   -> link to /TCID-DIR-AUTH-LOCAL-ADMIN

That's what I needed, and there's definitively something wrong happening here

---

Note: it's possible to ignore broken links with the 'onBrokenLinks' Docusaurus configuration.

You can temporarily ignore those broken link errors, did you try this 'onBrokenLinks' setting?

[bhaskarhc]

In my case all links are breaking.
Didn't try brokenLink settings . I dont want to ignore any link / page / doc .

[daniellavoie]

Hi, I'm also encountering problems with broken link. In my case, it seems that relative path are not resolved properly

Here's a snippet of my document.

* A Reserved [RFC1918](https://en.wikipedia.org/wiki/Private_network#Private_IPv4_addresses) /24 CIDR (e.g.: `10.114.23.0/24`) as per [reference architecture](reference-architecture)

Generates this error:

- Page path = /docs/gcp/install:
   -> link to /reference-architecture

It seems that the path are now absolute and not relative.

It don't think this is a reporting issue that can be ignored with the brokenLink setting. I have the feeling that the latest version can't handle relative paths.

[slorber]

Yes I've noticed some strange behavior reported, will try to see where the regression comes from.

I think if you reference the docs with the .md extension it will work, but will try to get this fixed asap and publish a new version

[daniellavoie]

I also noticed a problem with external link references

Snippet in my document

* [5.5.0 Helm chart for Grafana](https://github.com/helm/charts/tree/master/stable/grafana)

Produces:

- Page path = /docs/grafana:
   -> link to /(https://github.com/helm/charts/tree/master/stable/grafana)

There's a weird front slash in the external URL.

[daniellavoie]

I'm feeding more info as this may help with the investigation. For the given url:

as per [reference architecture](reference-architecture.md)

It get resolved to http://localhost:3000/reference-architecture which is an absolute path and not a relative one. I tried without .md and I get the same result.

[slorber]

Yes I think there's a leading / added by mistake in relative links, will check where to remove it.

@daniellavoie for me using the .md extension does produce absolute links:

[theme](using-themes.md)
href: "/docs/next/test/using-themes"

[theme](using-themes)
href: "/using-themes"

If you don't have this behavior this is surprising.

[daniellavoie]

I confirm I get the same broken link with and without .md. I'll wait for the fix on the leading slash before worrying about this specific behaviour.

[slorber]

I have a fix ready, but @daniellavoie this is totally unrelated to how links to .md extensions are resolved, this part of the code did not change recently, so please double-check that referencing a md file path work for you (it should).

If this does not work, it's a totally different bug to report with the full details

[slorber]

Will be fixed in next release (probably tomorrow)

[davenquinn]

FYI: I cannot find any documentation on the location or signature of the onBrokenLinks config setting to disable this behavior. This should be intergrated into whatever fix you create.

[slorber]

https://v2.docusaurus.io/docs/docusaurus.config.js/#optional-fields

It takes 4 possible values, as documented

[davenquinn]

I stand corrected!

I was also able to find this in the original typescript defs, but nice work on the documentation search.

[bhaskarhc]

Will be fixed in next release (probably tomorrow)

@slorber is issue fixed version avaliable now ?

[slorber]

Hi, not yet but I will release in the next hours (unless there's a new important bug reported)

[viztastic]

I've just upgraded to alpha 61 and getting this error when I run npx docusaurus --version :

Tried to find where in the release notes it describes links as being renamed to items but I couldn't. Is this expected behaviour?

[teikjun]

@viztastic Yes, this is the expected behavior. It was renamed in alpha.59, but it was not stated explicitly in the release notes.
You can just rename links to items and it should be good :)

[slorber]

yes sorry it's not very visible on the changelog (should probably highlight more by editing the changelog next time) but it is in one of the PRs in the breaking changes: https://github.com/facebook/docusaurus/pull/2971