Getting broken link on existing document path #7247

dprothero · 2022-04-26T22:44:48Z

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

Run npx create-docusaurus@latest my-website classic
cd my-website
Add a docs/tutorial-basics/quickstart/quickstart.md file with any contents.
Adde a link to the new quickstart.md in the docs/intro.md file.
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.

The text was updated successfully, but these errors were encountered:

Josh-Cena · 2022-04-27T00:15:08Z

Hi, it may be a bit counter-intuitive, but file paths are resolved relative to (a) the current file or (b) the content path root. This means for a link like /docs/tutorial-basics/quickstart/quickstart.md in the file /docs/tutorial-basics/intro.md (added another layer for illustration), we will attempt the following:

Relative to the current file. This should be the most intuitive because it's also how people import JavaScript or expect most Markdown renderers to behave. So we'll try /docs/tutorial-basics/docs/tutorial-basics/quickstart/quickstart.md; non-existent. (TBH, I don't think we should try it in this case, because /docs/... is an absolute path, not a relative one)
Relative to the content directory, which by default is docs. Therefore, we would try /docs/docs/tutorial-basics/quickstart/quickstart.md; non-existent.

Now, many people think we should also try to resolve it from the site root. However, it's not very portable, because when you translate the page by copying Markdown files, you would then need to manually update the links to point to the localized directory (which is /i18n/zh-Hans/plugin-content-docs instead of /docs). It's the same reason why we don't make absolute paths actual absolute paths (i.e. we never accept something like /Users/Josh-Cena/Desktop/website/docs/intro.md, because it's absolutely non-portable).

I think there are several points of improvements we can make here, plus having some clearer docs. I would keep this open to remind me of the refactor.

dprothero · 2022-04-27T15:18:07Z

Yeah, it feels like a comprehensive doc showing different examples is in order.

It gets extra confusing because /docs/tutorial-basics/quickstart/quickstart works fine.

Josh-Cena · 2022-04-27T15:37:21Z

/docs/tutorial-basics/quickstart/quickstart works fine.

Paths sans the .md extension is a URL path, not a file path, so it follows URL semantics instead of going through Docusaurus resolution. The new documentation is ready for preview here: https://deploy-preview-7248--docusaurus-2.netlify.app/docs/markdown-features/links/

dprothero · 2022-04-27T15:41:16Z

I could use some help with a particular case, then, because even your description of how it should work isn't working for me.

Directory structure:

- docs
  - gateways [one docs plugin instance]
    - rest-api
      - intro.md
      - quickstart
        - quickstart.md
  - writing [another docs plugin instance]
    - writing-guide
      - planning.md

I am trying to link from planning.md to quickstart.md with Markdown like this:

Visit the [REST API Gateway Quickstart](/gateways/rest-api/quickstart/quickstart.md) for an example.

Here are the forms of the URL that I have tried (and all report an issue):

/gateways/rest-api/quickstart/quickstart.md (your description leads me to believe this should have worked)
/docs/gateways/rest-api/quickstart/quickstart.md
../../gateways/rest-api/quickstart/quickstart.md (your description leads me to believe this relative link should work)
/docs/gateways/rest-api/quickstart/quickstart
../../gateways/rest-api/quickstart/quickstart

And, in fact, the error reporting is also saying it's resolving to a file path that really exists, for example, for the very last path in the list above, the error is:

- On source page path = /docs/writing/writing-guide/planning:
   -> linking to ../../gateways/rest-api/quickstart/quickstart (resolved as: /docs/gateways/rest-api/quickstart/quickstart)

Shouldn't "resolved as" be the full path that it's resolving to? Why does it report an error if that path actually exists?

And, the thing I'm really struggling with is, just a few lines above in planning.md, I have the following:

Visit the [REST API Gateway](/docs/gateways/rest-api/intro) product docs for an example.

And that reports no error!

Josh-Cena · 2022-04-27T15:43:21Z

Do you have onBrokenMarkdownLinks config? Does it report any errors?

dprothero · 2022-04-27T15:45:52Z

Yes onBrokenMarkdownLinks: "warn", and the warnings do appear for some cases, but not others... I'll document for which paths the warnings appear in the next comment.

dprothero · 2022-04-27T15:54:14Z

These paths show TWO (2) warnings during build:

/gateways/rest-api/quickstart/quickstart.md

[WARNING] Docs markdown link couldn't be resolved: (/gateways/rest-api/quickstart/quickstart.md) in /Users/dprothero/Projects/internal-product-docs/docs/writing/writing-guide/planning.md for version current
[WARNING] Docs markdown link couldn't be resolved: (/gateways/rest-api/quickstart/quickstart.md) in /Users/dprothero/Projects/internal-product-docs/docs/writing/writing-guide/planning.md for version current

/docs/gateways/rest-api/quickstart/quickstart.md

[WARNING] Docs markdown link couldn't be resolved: (/docs/gateways/rest-api/quickstart/quickstart.md) in /Users/dprothero/Projects/internal-product-docs/docs/writing/writing-guide/planning.md for version current
[WARNING] Docs markdown link couldn't be resolved: (/docs/gateways/rest-api/quickstart/quickstart.md) in /Users/dprothero/Projects/internal-product-docs/docs/writing/writing-guide/planning.md for version current

../../gateways/rest-api/quickstart/quickstart.md

[WARNING] Docs markdown link couldn't be resolved: (../../gateways/rest-api/quickstart/quickstart.md) in /Users/dprothero/Projects/internal-product-docs/docs/writing/writing-guide/planning.md for version current
[WARNING] Docs markdown link couldn't be resolved: (../../gateways/rest-api/quickstart/quickstart.md) in /Users/dprothero/Projects/internal-product-docs/docs/writing/writing-guide/planning.md for version current

These paths show no warnings during build, but the build still fails with a broken link error message:

/docs/gateways/rest-api/quickstart/quickstart
../../gateways/rest-api/quickstart/quickstart

UPDATE: I tried these last two again after running docusaurus clear and the build still fails.

slorber · 2022-04-27T16:05:43Z

@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 doc will be at /docs/quickstart instead of previously being at /docs/quickstart/quickstart.

This is likely why you saw an error on your site after upgrading

slorber · 2022-04-27T16:09:52Z

Also, when the broken link checker reports this:

- On source page path = /docs/writing/writing-guide/planning:
   -> linking to ../../gateways/rest-api/quickstart/quickstart (resolved as: /docs/gateways/rest-api/quickstart/quickstart)

It doesn't mean that the markdown relative file link was resolved, it just prints the "relative path" being converted to an absolute path. The broken link checker doesn't know anything about resolving .md file paths, it can just compare regular URLs, not file paths.

I understand how it can be a bit confusing here, but the "markdown file resolution" and the "broken links checked resolved as" are 2 different things somehow:

One resolves relative file path to an absolute url
The other resolves relative URLs to absolute URLs so that we can compare them to known site routes

dprothero · 2022-04-27T16:22:15Z

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.

slorber · 2022-04-27T16:24:57Z

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 added bug An error in the Docusaurus core causing instability or issues with its execution status: needs triage This issue has not been triaged by maintainers labels Apr 26, 2022

Josh-Cena added closed: working as intended This issue is intended behavior, there's no need to take any action. and removed status: needs triage This issue has not been triaged by maintainers labels Apr 27, 2022

Josh-Cena mentioned this issue Apr 27, 2022

refactor: normalize Markdown linkification behavior, elaborate in documentation #7248

Merged

Josh-Cena closed this as completed in #7248 Apr 29, 2022

robbiejackson mentioned this issue Jul 18, 2024

Improve Get Started introductory page joomla/Manual#284

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Getting broken link on existing document path #7247

Getting broken link on existing document path #7247

dprothero commented Apr 26, 2022

Josh-Cena commented Apr 27, 2022 •

edited

Loading

dprothero commented Apr 27, 2022

Josh-Cena commented Apr 27, 2022

dprothero commented Apr 27, 2022

Josh-Cena commented Apr 27, 2022

dprothero commented Apr 27, 2022

dprothero commented Apr 27, 2022 •

edited

Loading

slorber commented Apr 27, 2022

slorber commented Apr 27, 2022 •

edited

Loading

dprothero commented Apr 27, 2022

slorber commented Apr 27, 2022

Getting broken link on existing document path #7247

Getting broken link on existing document path #7247

Comments

dprothero commented Apr 26, 2022

Have you read the Contributing Guidelines on issues?

Prerequisites

Description

Reproducible demo

Steps to reproduce

Expected behavior

Actual behavior

Your environment

Self-service

Josh-Cena commented Apr 27, 2022 • edited Loading

dprothero commented Apr 27, 2022

Josh-Cena commented Apr 27, 2022

dprothero commented Apr 27, 2022

Josh-Cena commented Apr 27, 2022

dprothero commented Apr 27, 2022

dprothero commented Apr 27, 2022 • edited Loading

slorber commented Apr 27, 2022

slorber commented Apr 27, 2022 • edited Loading

dprothero commented Apr 27, 2022

slorber commented Apr 27, 2022

Josh-Cena commented Apr 27, 2022 •

edited

Loading

dprothero commented Apr 27, 2022 •

edited

Loading

slorber commented Apr 27, 2022 •

edited

Loading