Enable managing broken links from a report

[brunomartinspro]

Pre-flight checklist

• I have read the Contributing Guidelines on pull requests.
• If this is a code change: I have written unit tests and/or added dogfooding pages to fully verify the new behavior.
• If this is a new API or substantial change: the PR has an accompanying issue (closes #0000) and the maintainers have approved on my working plan.

Motivation

Since broken links were being generated from various sources like Redocusaurus, we needed a more flexible way to handle them. To solve this, i introduced the onReportBrokenLinks function, which allows us to manage each broken link individually based on specific business needs.

Usage:
https://deploy-preview-11101--docusaurus-2.netlify.app/docs/api/docusaurus-config#onReportBrokenLinks

Test Plan

When a broken link is detected, we should have the ability to handle it—such as removing it, in this case—before including it in the report.

Test links

Created a Unit Test:

• path: /packages/docusaurus/src/server/__tests__/brokenLinks.test.ts
• title: can warn for broken links and remove them before building the report
• description: Verifies that broken links can be detected and successfully removed from the final report

Deploy preview: https://deploy-preview-11101--docusaurus-2.netlify.app/docs/api/docusaurus-config

Related issues/PRs

#9986

[netlify]

✅ [V2]

Built without sensitive environment variables

Name	Link
🔨 Latest commit	f927499
🔍 Latest deploy log	https://app.netlify.com/sites/docusaurus-2/deploys/67fd10af7649fc0008ade2e5
😎 Deploy Preview	https://deploy-preview-11101--docusaurus-2.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[github-actions]

⚡️ Lighthouse report for the deploy preview of this PR

URL	Performance	Accessibility	Best Practices	SEO	Report
/	🔴 46	🟢 98	🟢 100	🟢 100	Report
/docs/installation	🔴 49	🟢 97	🟢 100	🟢 100	Report
/docs/category/getting-started	🟠 72	🟢 100	🟢 100	🟠 86	Report
/blog	🟠 59	🟢 96	🟢 100	🟠 86	Report
/blog/preparing-your-site-for-docusaurus-v3	🔴 45	🟢 92	🟢 100	🟢 100	Report
/blog/tags/release	🟠 63	🟢 96	🟢 100	🟠 86	Report
/blog/tags	🟠 73	🟢 100	🟢 100	🟠 86	Report

[slorber]

Could you reuse the existing onBrokenLinks and onBrokenAnchors APIs instead of introducing a new API that conflicts with the existing ones?

The API could be:

const config = {
  onBrokenLinks: ({brokenLinks, utils}) => {
    const message = utils.createBrokenLinksMessage({brokenLinks})
    console.error(message);
  }),

  onBrokenAnchors: ({brokenAnchors, utils}) => {
    const message = utils.createBrokenAnchorsMessage({brokenAnchors})
    console.warn(message);
  }),
}

Injecting an utils attribute permits to expose our existing functions to create messages. It's useful because people that want callbacks will usually want to filter the list or other similar operations, and may be less interested in creating a custom message.

Example use case: someone may decide that docs throw on broken links, but blog posts and other pages only warn. They should be able to "split" the list into 2 sublists, and report individual sublists.

const config = {
  onBrokenLinks: ({brokenLinks, utils}) => {
    const [docsBrokenLinks, otherBrokenLinks] = splitList(brokenLinks);
    if (docsBrokenLinks.length) {
      throw new Error(utils.createBrokenLinksMessage({brokenLinks: docsBrokenLinks}))
    }
    if (otherBrokenLinks.length) {
      console.warn(otherBrokenLinks);
    }
  }),

  onBrokenAnchors: "throw",
}

This API would give great flexibility for users to do fancy things we didn't think of.

Does it make sense?

I'll be back in a few days to follow up on this PR, until then I hope my review will be helpful.

👋

[slorber]

I'd prefer to avoid introducing a new API when we already have one

[brunomartinspro]

Im on Easter vacations but as soon as i get back i will look into the implementations.
Thank you 🙏