Getting broken link on existing document path

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

Docusaurus is reporting a broken link for a path that exists if the Markdown file is in a directory of the same name as the Markdown file. (e.g. /docs/tutorial/tutorial.md) See the reproducible demo.

Reproducible demo

https://github.com/dprothero/docusaurus-broken-links

Steps to reproduce

1. Run npx create-docusaurus@latest my-website classic
2. cd my-website
3. Add a docs/tutorial-basics/quickstart/quickstart.md file with any contents.
4. Adde a link to the new quickstart.md in the docs/intro.md file.
5. Run npm run build

This produces the following output:

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

Exhaustive list of all broken links found:

- On source page path = /docs/intro:
   -> linking to /docs/tutorial-basics/quickstart/quickstart.md

Expected behavior

It should not report a broken link. It should build successfully.

Actual behavior

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

Exhaustive list of all broken links found:

- On source page path = /docs/intro:
   -> linking to /docs/tutorial-basics/quickstart/quickstart.md

Your environment

• Public source code: N/A (source code is private)
• Public site URL: N/A (site is private)
• Docusaurus version used: 2.0.0-beta.18
• Environment name and version (e.g. Chrome 89, Node.js 16.4): Node.js v16.4.1, browser is N/A
• Operating system and version (e.g. Ubuntu 20.04.2 LTS): macOS Big Sur v11.6.4

Self-service

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

[slorber]

I should read the release notes carefully when upgrading.

That’s probably not your fault, nobody reads long changelogs anyway 😅

After 2.0 launch the goal is to do such changes on major versions and have a dedicated blog post with clearer instructions and breaking change highlights

[dprothero]

OK, so this was my root problem:

@dprothero a recent update we did: now /docs/quickstart/quickstart.md where dir/file have the exact same name, by convention the doc becomes the “index” of that folder/category, and the doc filename does not contribute anymore to the final doc slug/url

The other, somewhat confusing methods of URL resolution led me to believe I had reproduced the issue in the repo.

Lessons learned:

• I should read the release notes carefully when upgrading.
• The URL resolution methods need some docs love, which is happening. (I checked the preview site and the changes look great)!

So, this issue can be closed, unless you want to keep it open until the docs changes are released.