"Docs markdown link couldn't be resolved" infinite loop on build or start

[Southclaws]

🐛 Bug Report

I upgraded to 66 recently for our docs site and since we're doing translations that are in-progress, there are a lot of broken links (because translators copy the english, change the text and keep the markdown - so links and images, etc) which is fine, I don't want translators to remove links then re-add them later it'll just get confusing. I have set onBrokenLink to ignore but the warning messages still appear.

The issue is whenever I do a build or run the dev server the console just gets inundated with:

Docs markdown link couldn't be resolved: ...

I thought there were just a lot of links so I left it running for 10 minutes and it's still printing! It seems to be stuck in an infinite loop as it prints the same thing over and over. It opens the browser but the page never loads.

I'm thinking it's related to the type of TTY though because on Vercel it builds fine (ignoring the other error) https://vercel.com/openmultiplayer/wiki/4wphzsm3e could it be related to that progress bar graphic that appears in the terminal?

It seems to be TTY related, if I pipe the output to a file then the server starts up fine:

wiki on  master [$✘] via ⬢ v12.18.3 took 2m48s
❯ npm start > logs
Docs markdown link couldn't be resolved: (NPC:StartRecordingPlayback.md) in E:\Work\open.mp\wiki\docs\scripting\callbacks\OnRecordingPlaybackEnd.md for version current
Docs markdown link couldn't be resolved: (NPC:StopRecordingPlayback.md) in E:\Work\open.mp\wiki\docs\scripting\callbacks\OnRecordingPlaybackEnd.md for version current
[BABEL] Note: The code generator has deoptimised the styling of E:\Work\open.mp\wiki\docs\scripting\resources\animations.md as it exceeds the max of 500KB.
Docs markdown link couldn't be resolved: (../resources/weaponskills#skill-levels.md) in E:\Work\open.mp\wiki\docs\scripting\functions\SetPlayerSkillLevel.md for version current
Docs markdown link couldn't be resolved: (../scripting/functions/GetPlayerDrunkLevel.md) in E:\Work\open.mp\wiki\docs\scripting\functions\SetPlayerDrunkLevel.md for version current
Docs markdown link couldn't be resolved: (GetVehicleRotation.md) in E:\Work\open.mp\wiki\docs\scripting\functions\GetVehicleZAngle.md for version current
Docs markdown link couldn't be resolved: (GetVehicleRotation.md) in E:\Work\open.mp\wiki\docs\scripting\functions\GetVehiclePos.md for version current
Docs markdown link couldn't be resolved: (../tutorials/colorfix.md) in E:\Work\open.mp\wiki\docs\scripting\functions\GetPlayerColor.md for version current
Docs markdown link couldn't be resolved: (UpdatePlayer3DTextLabel.md) in E:\Work\open.mp\wiki\docs\scripting\functions\Attach3DTextLabelToVehicle.md for version current
Docs markdown link couldn't be resolved: (UpdatePlayer3DTextLabel.md) in E:\Work\open.mp\wiki\docs\scripting\functions\Attach3DTextLabelToPlayer.md for version current

And it stops printing there, the browser opens as expected and I can browse/edit the site and it reloads live.

Have you read the Contributing Guidelines on issues?

Yes

To Reproduce

I think just having a ton of 404s triggers it, clone this and build it: https://github.com/openmultiplayer/wiki/

Your Environment

Does not occur on Vercel but occurs locally on Windows.

[slorber]

Hi,

I'm not sure what's the error that you are reporting here?
Is it just the infinite loop, or is it also the error message?
Because I see your Vercel deployment also has this error message.

As far as I understand it is a cosmetic terminal issue, and is not blocking you from building your site right?

Note: I'm working on proper i18n support right now, will soon look for early adopters to onboard

[Southclaws]

It seems to be stuck in an infinite loop as it prints the same thing over and over. It opens the browser but the page never loads.

The page on localhost never loads, but if I pipe output to a file, it works fine. I think it's detecting if it's writing to a TTY and if it is, redrawing the entire terminal because normally there's a progress bar for the client and server build.

Here's a video: https://i.imgur.com/NhLGNZs.mp4

Notice how the scroll bar starts to grow just for this progress, each render adds more lines to the terminal:

As soon as the 404 errors start to print, the buffer starts to fill up. If I leave it running, it just does this constantly.

It might not actually be an "infinite loop" though, it might just be the constant writes to stdout slowing down the process so it just takes an insanely long time to actually build and serve content.

---

On the topic of translations, we'll be very interested in trialing that new feature, we've been anticipating its release! We have about 700 pages in each language and our number of languages is growing constantly so it's a big test-base!

[slorber]

Seems to work for me on macos with yarn install && yarn start

[ghost]

Not working for me, running wiki locally makes loop for 3 hours straight.
The problem keep repeating itself, idk why.

[slorber]

Can you both share your env?
Both on Windows?

[ghost]

I'm on windows.
Using cmd.

your env?

What do you mean?

[slorber]

your env?
What do you mean?

Anything useful to share. But knowing you are both on windows is a good first step 👍

Unfortunately, I don't have windows, but if someone can help figure this problem out that would be nice

[Cankar001]

What is the status here? I keep getting the same infinite loop and the local development server is not reachable due to this infinite loop warning. I am on Windows too and I tried to implement another documentation section for my API documentation. Inside the api docs I got cross-references to other markdown files and my sidebar js file is set to autogenerated and the dirName is correct as well

[Josh-Cena]

@Cankar001 We are looking for a contributor on Windows to look into this, because neither @slorber nor I have a Windows device. Unless you can point us to where the culprit is in our source code, this issue remains unactionable.

[Southclaws]

I'd love to help figure this one out but we moved off Docusaurus and wrote our own with next.js due to this issue and some others (I think the sheer size of our site caused issues, including translations there were somewhere near 10,000 pages)

The original repo I posted should still work though, and if anyone else does try to repro this it's probably worth updating Docusaurus first as the bug may not be present any more.

[Cankar001]

@Southclaws Thanks for the info! I am working on a large project as well, we probably will have a similar documentation size, I will discuss to move off docusaurus with the team then, thanks for your information! 👍

[Josh-Cena]

Indeed, I'd recommend finding alternatives to Docusaurus if you have 10,000 pages since we are not very memory/time efficient at this point. Would be interesting to see any benchmark of Docusaurus vs Next.js vs Gatsby etc. Maybe this problem itself is uniquely with large documentation sites then?

[Cankar001]

@Josh-Cena I don't think so, our documentation is very small at this point, we are still at the beginning of the project (we only have one blog post and about 10 documentation pages now). The problem occurred when I tried to integrate an api documentation section of a larger c++ code base (about 130 000 lines now) with many cross references (I generated the api documentation with doxygen using the XML output and then converted the XML output with Moxygen to Markdown. I placed all markdown files into a docs-api folder and followed the instructions on the official docusaurus site to integrate another documentation. That's when I got the infinite loop warning mentioned before. I also tried following this answer https://stackoverflow.com/a/68162605/12873837, but I got the same infinite loop warning.

[Josh-Cena]

So, in the end, you still have a lot of Markdown files to build, despite they being all autogenerated, right?

[Cankar001]

Yes that is correct, currently we have 264 auto-generated markdown files

[Josh-Cena]

Are you (and @Southclaws) using Windows when that error manifests itself? Two people reporting are using windows, and two people are building large documentations (although 264 doesn't sound terribly large—wonder how long they are and how many links they have though!). I wonder what's the intersection of the two sets.

[slorber]

@Cankar001 that would be helpful if you can provide a small repro of the problem.

If you generate your content and then remove a lot of pages progressively until you reach an empty site, maybe you could identify which page exactly is triggering this problem?

I believe a newly initialized site works fine for you right? So this dichotomy debugging technique might be useful 🤪

[Cankar001]

@slorber Hi, sorry for not responding, I had a lot to do in the last days in university.

I added the not working version to the public github repository: https://github.com/HighLo-Engine/docs-old
The github action is responsible for building and uploading the documentation to the webserver: https://github.com/HighLo-Engine/docs-old/runs/5527808922?check_suite_focus=true

The github action failed with the mentioned infinite loop warning.
A newly initialized site works as long as I don't add the generated api documentation to the docusaurus.config.js file.

I hope these information help you, if you need anything else, just let me know :)

[slorber]

@Cankar001 the github action does not fail due to the mentioned infinite loop: it fails due to the error printed in that github action:

And locally, the dev server does not have an infinite loop, it has the exact same error.

This is just one page of your site that seems to have a syntax error due to using <int32> which MDX understands as a JSX element

The fix is easy:

- usability improvement:we currently have duplicated usage, you can achieve the same result with either: std::vector<int32> arr; arr.push_back(10); arr.push_back(42);
+ usability improvement:we currently have duplicated usage, you can achieve the same result with either: `std::vector<int32>` arr; arr.push_back(10); arr.push_back(42);

---

Now regarding the warnings

[WARNING] Docs markdown link couldn't be resolved: (docs-api/api-highlo--Event.md) in /Users/x/Desktop/docs-old/docs-api/api-highlo.md for version current

Both files are in the exact same folder so you should not use a docs-api prefix

- `class `[`highlo::Event`](docs-api/api-highlo--Event.md#classhighlo_1_1_event) | 
+ `class `[`highlo::Event`](./api-highlo--Event.md#classhighlo_1_1_event) | 

Indeed you can see Docusaurus is 100% right to report this warning, because your linking is bad.

http://localhost:3000/api/api-highlo links to http://localhost:3000/api/docs-api/api-highlo--Event.md#classhighlo_1_1_event (which does not exist => 404)

Try to click here and see for yourself:

---

Now I can't tell if there's an infinite loop or not on Windows, but this repro is not really acceptable because it contains a lot of errors.

We'll need someone to be able to produce a better repro, preferably smaller too and without such errors

Here, all the produced warnings are real problems reported by Docusaurus, not meant to be ignored

---

Maybe an infinite loop happens on Windows, only when such errors are printed. In this case please make sure that it works with 0 warning and starts failing when we introduce 1-n linking warning

[Cankar001]

@slorber Thank you very much! I will try to fix the mentioned issues and come back to you if the infinite loop warning still remains :)

[Josh-Cena]

Closing again due to inactivity

[evisdrenova]

I'm getting this same error now but it's happening in my node-modules. The site builds fine and I can run it locally, but when I go to deploy it on Vercel, it doesn't work consistently. Sometimes it throws these errors other times it doesn't. It throws these warnings:

[WARNING] Docs markdown link couldn't be resolved: (docs/definition-syntax.md) in "/vercel/path1/docs/node_modules/css-tree/README.md" for version current
10:37:52.882 | [WARNING] Docs markdown link couldn't be resolved: (docs/definition-syntax.md) in "/vercel/path1/docs/node_modules/css-tree/README.md" for version current
10:37:52.882 | [WARNING] Docs markdown link couldn't be resolved: (docs/definition-syntax.md) in "/vercel/path1/docs/node_modules/css-tree/README.md" for version current
10:39:14.372

then later on in the log lines throws this error:

SyntaxError: /vercel/path1/docs/node_modules/@alloc/quick-lru/readme.md: Expected corresponding JSX closing tag for <br>. (89:1)
--
10:39:14.456 | 87 \| 	<sub>
10:39:14.456 | 88 \| 		Tidelift helps make open source sustainable for maintainers while giving companies<br>assurances about security, maintenance, and licensing for their dependencies.
10:39:14.456 | > 89 \| 	</sub>
10:39:14.456 | \| 	^
10:39:14.456 | 90 \| </div>
10:39:14.456 | 91 \|     </MDXLayout>
10:39:14.456 | 92 \|   )
10:39:14.456 | SyntaxError: /vercel/path1/docs/node_modules/@babel/code-frame/node_modules/ansi-styles/readme.md: Unterminated JSX contents. (122:16)
10:39:14.456 | 120 \| <h2 {...{"id":"license"}}>{`License`}</h2>
10:39:14.456 | 121 \| <p>{`MIT`}</p>
10:39:14.456 | > 122 \|     </MDXLayout>
10:39:14.456 | \|                 ^
10:39:14.456 | 123 \|   )
10:39:14.456 | 124 \| };
10:39:14.456 | 125 \| MDXContent.isMDXComponent = true

Since it's in our node_modules, I'm not exactly sure how to resolve this?

[Josh-Cena]

@evisdrenova Your error is unrelated. It's because your Docusaurus is trying to load node_modules as part of your docs. Please start a discussion and provide a reproduction.

[evisdrenova]

@Josh-Cena sure will do!