How to Detect and Fix Broken Links?

[nelsonic]

Since moving to Nextra many of the internal links in our docs are broken ... 💔 😢
One thing that Docusaurus gave us out-of-the-box was checking links. 🦕 📜
We need to investigate if Nextra has the feature to check all links in a page and confirm they work. 🔗 👍

Todo

• Investigate if Nextra has a built-in way to check internal links to confirm they aren't 404. 📥
• Same for external links but this probably won't be a thing as it requires making outbound HTTP requests. 🌐

If there is an easy way to check the internal links please share and implement on this demo with instructions. 📝 🙏
Please add comments for your searches and pages you read along the way so others don't have to waste the same time. ⏳

[LuchoTurtle]

Nextra doesn't have much information about linting and validating internal links :( The only reference to internal links is in https://nextra.site/docs/guide/link, which just explains how they render the links in mdx files and convert it to Next.js's Link components. There doesn't seem to be any issues or discussions regarding this in their repo either.

However, I've found a couple of packages that may tackle this issue:

• https://www.reddit.com/r/nextjs/comments/1aonrjs/you_dont_have_worry_about_broken_links_in_your/
• https://github.com/ckastbjerg/next-type-safe-routes

Let me give these a whirl.

[LuchoTurtle]

I've been trying a couple of options:

https://github.com/ckastbjerg/next-type-safe-routes

Using https://github.com/ckastbjerg/next-type-safe-routes was my first attempt. However, this attempt was not successful. On my first attempt to get it to work, I was met with a lot of errors.

However, even with these, the routes were not being properly validated. And there was no discernable way of actually linting the links at build time/running on dev mode.

In addition to this, it seemed that rewrites was not properly supported (as discussed in ckastbjerg/next-type-safe-routes#15), so we couldn't properly use this plugin.

https://github.com/triyanox/next-routes

Came across this one on Reddit and seemed promising. However, having tried to incorporate this into our Nextra app, it seemed that this package is oriented to the routing made with the App Router and not with Pages Router. Additionally, it didn't support the file directory with .mdx files or slugs (which it would have been a similar way of parsing the files).

So unfortunately, this was a dud :(

https://github.com/contentlayerdev/contentlayer

contentlayer is used to get the site's data. It supports Next.js , and by extension, Nextra.

I thought of using contentlayer with https://github.com/tcort/markdown-link-check to recursively go over through the site data (generated by contentlayer and check the URLs that are found within the mdx files.

Note

tcort/markdown-link-check#216 states that localhost links may not work in later versions but I'm using the latest versions still because they are still found (using 3.12.2).

So, I set out to integrate contentlayer in this demo, following https://www.imadatyat.me/guides/how-to-setup-contentlayer-in-nextjs#add-a-jsconfigjson-file.

After setting all of the necessary imports, files and configuration to the demo, when trying to run contentlayer build in my package.json file, I was prompted with the following error:

Generated 11 documents in .contentlayer
TypeError: The "code" argument must be of type number. Received an instance of Object
    at process.set [as exitCode] (node:internal/bootstrap/node:123:9)
    at Cli.runExit (/Users/lucho/Documents/dwyl/nextra-demo/node_modules/.pnpm/[email protected][email protected]/node_modules/clipanion/lib/advanced/Cli.js:232:26)
    at run (file:///Users/lucho/Documents/dwyl/nextra-demo/node_modules/.pnpm/@[email protected][email protected]/node_modules/@contentlayer/cli/src/index.ts:39:3)
    at main (/Users/lucho/Documents/dwyl/nextra-demo/node_modules/.pnpm/[email protected][email protected]/node_modules/contentlayer/bin/cli.cjs:5:3) {
  code: 'ERR_INVALID_ARG_TYPE'
}

The files are actually being generated.

But the error cumbersomely still pops up. So I found out about the issue contentlayerdev/contentlayer#495, where the error seemed to be related with the Node version. Long story short, Node 18 works but Node 19 had deprecated a piece of code at https://nodejs.org/api/deprecations.html#DEP0164 that no longer exists in Node 20. I'm not willing to downgrade to Node 20 for this.

Looking over the issues in the repo, I came across contentlayerdev/contentlayer#429 (comment). Apparently, Netlify acquired the project and it was put on the back burner (why is Netlify slowly killing acquired FOSS projects? 🤔). So, following the recommendation of contentlayerdev/contentlayer#651 (comment), while they are coordinating the maintenance roadmap for the project, I'm going to have to use https://github.com/timlrx/contentlayer2, a fork of the original project that is actively being maintained (and hopefully, in the future, will have its changed merged back into the official upstream contentlayer package).

After migrating, I'm trying to run the markdownLintCheck from markdown-lin-check but I'm coming across an error similar to the one described in tcort/markdown-link-check#272.

Going to try and move over this hurdle.

[LuchoTurtle]

Hmm, I almost got it working with the combination of contentlayer2 and markdown-link-check. But now I've stumbled upon https://github.com/theoludwig/markdownlint-rule-relative-links and maybe I can use this too (or replace everything completely with this? It doesn't check if the path exists, just if the file does (which is ultimately the same thing? 🤔)

[nelsonic]

@LuchoTurtle thanks very much for taking a deep dive into this. 🙏
My takeaway is: this is not a built-in feature of Nextra ... 😕
Feels like it should be. 🤷‍♂️

Keen to see what you have to do to get this working. 👍
But equally I'm leaning towards proposing using (building) something else that better suits our (client's) needs. 💭

Edit: for complete clarity: keep going on this for now.