Generating broken links for certain symbol combinations in markdown files

[bo-carey]

Have you read the Contributing Guidelines on issues?

• [X] I have read the Contributing Guidelines on issues.

Prerequisites

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

Description

There seems to be a bug in resolving broken links when certain symbols are used in conjunction.

example:

[`Type1`](some_doc.md#type1)\<[`Type2`](some_doc.md#type2)\>

This example generates a broken link to some_doc.md#type2

Here is a link to a sandbox with the error reproduced. Note the ./docs/index.md file for the broken bits.

Reproducible demo

https://codesandbox.io/p/sandbox/fervent-joana-2wypc8

Steps to reproduce

In a markdown file, add links using the following symbols:

[`Type1`](some_doc.md#type1)\<[`Type2`](some_doc.md#type2)\>

Expected behavior

A link is generated that looks like this:

<a href="/docs/some_doc#type1"><code>Type1</code></a>&lt;<a href="/docs/some_doc#type2"><code>Type2</code></a>&gt;

Actual behavior

A link is generated that looks like this:

<a href="/docs/some_doc#type1"><code>Type1</code></a>&lt;<a href="/docs/some_doc.md#type2"><code>Type2</code></a>&gt;

Your environment

No response

Self-service

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

[ruchikamuddinagiri]

Hi, can I work on this?

[Josh-Cena]

Cross-linking #9553: please add the following to the tests too:

Description

with docusaurus 3.0.0 a url is broken if the first url has a anchor ([a](./file.md#anchor)) and the second url uses the same url, but is in parenthesis (([b](./file.md#anchor])), fuller example:

[a](./migration/migrate-6.md#hooks) ([b](./migration/migrate-6.md#hooks))

this does not occur if no parenthesis are used:

[a](./migration/migrate-6.md#hooks) [b](./migration/migrate-6.md#hooks)

or if the first url does not have a anchor:

[a](./migration/migrate-6.md) ([b](./migration/migrate-6.md#hooks))

PS: removing (or changing) the "id:" in the target file does not change the error

Reproducible demo

https://github.com/typegoose/typegoose/tree/docusuaursV3urlError

[bo-carey]

I have confirmed that there are still broken links being generated after the release of v3.0.1. In that regard, there is no effectual change in behavior.

[monica-m-ps]

I also get the same broken links error when trying to upgrade..

- On source page path = /payments/accept-payments/checkout-page/configuration:
     -> linking to checklist.md (resolved as: /payments/accept-payments/checkout-page/checklist.md)
  
  - On source page path = /payments/accept-payments/checkout-page/step-by-step-guide:
     -> linking to ../../development-resources/webhooks.md (resolved as: /payments/development-resources/webhooks.md)

This works well in the previous version. I have a long list of these errors. Pasted just these as references.

My current format is

[a](./migration/migrate-6.md#hooks) [b](./migration/migrate-6.md#hooks)

[fredrik-jansson-se]

I've noticed the following markdown also generates broken links, i.e. with a newline:

[DNS 
chapter](./dns.md).

Generates the following error:

  - Broken link on source page path = /fundamentals/application-networking:
     -> linking to ./dns.md (resolved as: /fundamentals/dns.md)

[DNS chapter](./dns.md).

Works well.

This used to work in v2, but not in v3.1.0

[F-OBrien]

I just updated to v3 and now have issues with many links generated by typdoc. The broken link pattern is similar to that reported by @bo-carey.

in the below Link2 and Link3 are both broken

\<[`Link1`](file1.md#heading)\<[`Link2`](file2.md#heading)anyContiniousTextHere[`Link3`](file3.md#heading)\>\>

It seems I need at least 1 space anywhere between broken links to fix the issue. e.g.

\<[`Link1`](file1.md#heading) \<[`Link2`](file2.md#heading)spaced text here[`Link3`](file3.md#heading)\>\>

For my case if I do a find and replace )\<[ with ) \<[ to add a space between links then the links in the generated types are fixed.

[hasezoey]

Just retested with 3.2.0, and i can still reproduce the issue there (at least with the ways i had lined out in #9553 / reproduction repository)

updated error:

[ERROR] Error: Unable to build website for locale en.
    at tryToBuildLocale (/mnt/projects/nodejs/typegoose/website/node_modules/@docusaurus/core/lib/commands/build.js:53:19)
    at async /mnt/projects/nodejs/typegoose/website/node_modules/@docusaurus/core/lib/commands/build.js:64:9
    at mapAsyncSequential (/mnt/projects/nodejs/typegoose/website/node_modules/@docusaurus/utils/src/jsUtils.ts:21:20)
    at async Command.build (/mnt/projects/nodejs/typegoose/website/node_modules/@docusaurus/core/lib/commands/build.js:62:5) {
  [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 = /typegoose/docs/guides/advanced/reference-other-classes:
     -> linking to ../../api/functions/typeguards/isDocument.md#isdocumentarray (resolved as: /typegoose/docs/api/functions/typeguards/isDocument.md#isdocumentarray)
  - Broken link on source page path = /typegoose/docs/guides/error-warning-details:
     -> linking to ./migration/migrate-6.md#hooks (resolved as: /typegoose/docs/guides/migration/migrate-6.md#hooks)
  
      at throwError (/mnt/projects/nodejs/typegoose/website/node_modules/@docusaurus/logger/src/index.ts:135:9)
      at reportBrokenLinks (/mnt/projects/nodejs/typegoose/website/node_modules/@docusaurus/core/lib/server/brokenLinks.js:242:47)
      at handleBrokenLinks (/mnt/projects/nodejs/typegoose/website/node_modules/@docusaurus/core/lib/server/brokenLinks.js:274:5)
      at executeBrokenLinksCheck (/mnt/projects/nodejs/typegoose/website/node_modules/@docusaurus/core/lib/commands/build.js:182:47)
      at /mnt/projects/nodejs/typegoose/website/node_modules/@docusaurus/core/lib/commands/build.js:136:66
      at Object.async (/mnt/projects/nodejs/typegoose/website/node_modules/@docusaurus/core/lib/utils.js:36:47)
      at buildLocale (/mnt/projects/nodejs/typegoose/website/node_modules/@docusaurus/core/lib/commands/build.js:136:30)
      at async tryToBuildLocale (/mnt/projects/nodejs/typegoose/website/node_modules/@docusaurus/core/lib/commands/build.js:46:13)
      at async /mnt/projects/nodejs/typegoose/website/node_modules/@docusaurus/core/lib/commands/build.js:64:9
      at mapAsyncSequential (/mnt/projects/nodejs/typegoose/website/node_modules/@docusaurus/utils/src/jsUtils.ts:21:20)
}
[INFO] Docusaurus version: 3.2.0
Node version: v21.6.2

[slorber]

Going to close as a duplicate of https://github.com/facebook/docusaurus/issues/9048 because this is the real issue that we need to fix to resolve that bug properly.