feat(v2): onBrokenMarkdownLinks config

[AmyrAhmady]

Motivation

Fixing issue #3652

Little additional info:

We have a website which uses Docusaurus v2, and recently, we are letting people to contribute to the project and translate existing pages to their own language in separate folders; This means relative markdown links are still there in newly translated pages while those pages might not exist in the language's folder (as I mentioned, those links are relatively written there)

An example of this behaviour would be this: Click Here, and first item of that list does not exist. This was just an example that leads to printing only one error to stdout, for the real issue please refer to #3652

And at the end, there was a comment there saying this: https://github.com/facebook/docusaurus/blob/master/packages/docusaurus-plugin-content-docs/src/index.ts#L314

Have you read the Contributing Guidelines on pull requests?

I'd be lying if I say I've read it fully and carefully, but I tried to cherry pick needed parts but scrolling through, sorry :)

Test Plan

Not sure how exactly we are supposed to test that, but I guess running an instance of Docusaurus with "onBrokenLinks": "ignore" in site configurations and a dummy doc page with a broken relative link would be fine.

Here's a screenshot (I've heard rumors it has bonus points!)

Related PRs

None I guess?

[facebook-github-bot]

Hi @AmyrAhmady!

Thank you for your pull request and welcome to our community. We require contributors to sign our Contributor License Agreement, and we don't seem to have you on file.

In order for us to review and merge your code, please sign at https://code.facebook.com/cla. If you are contributing on behalf of someone else (eg your employer), the individual CLA may not be sufficient and your employer may need to sign the corporate CLA.

If you have received this in error or have any questions, please contact us at cla@fb.com. Thanks!

[docusaurus-bot]

Deploy preview for docusaurus-2 ready!

Built with commit 16ad52a

https://deploy-preview-3658--docusaurus-2.netlify.app

[facebook-github-bot]

Thank you for signing our Contributor License Agreement. We can now accept your code for this (and any) Facebook open source project. Thanks!

[slorber]

Hi and thanks for completing my todo :)
That looks pretty good overall.

There's for me one major problem: if you have 2 MD broken links and the throw config (recommended, default config), you might fail on first md broken link found.
In such case only one broken link would be reported: the first one.

We'd rather find a way to aggregate all the md broken links here instead of failing fast asap?
Maybe storing a mutable broken links list in the plugin, and reporting all the broken links once all the docs have been read?

If that's not possible, I'd rather have a 2nd option like siteConfig.onMarkdownBrokenLink or something, that would rather default to a warning, so that user might see all the md broken links in a single build attempt.

The important thing to me is that the user does not have to fail a build, fix 1 link, fail another build, fix another link etc... he should see all the broken links by default.

Does it make sense?

[AmyrAhmady]

I have just pushed two commits, containing changes and features you've asked above :)
What I did making broken markdown links independently configurable so we don't need to mix them up with actual broken links;
That being said, we now have a totally new option in site configs, called onBrokenMarkdownLinks and works exactly like onBrokenLinks, and its default value is set to warn

Let me know if there's anything needed

EDIT: Don't get me wrong, I'm doing force pushes to avoid having extra random commits for small fixes by doing amend, just wanted to have a clean contribution

[slorber]

thanks, that looks great :)

No need to doc for alpha 66, as this will only be released in 67.

Also we squash all PRs so your git commit history does not matter much

[AmyrAhmady]

Nice! thanks, also I know this isn't the right place to ask, but is there any planned release date for alpha 67?

[slorber]

we plan to release during the next week

[zepatrik]

Released with https://github.com/facebook/docusaurus/releases/tag/v2.0.0-alpha.68 🎉