Fail-safe build strategy

[000user]

🚀 Feature

Implement a toggle switch which ignores/moves/removes faulty md/doc files found while compiling into static html.

Have you read the Contributing Guidelines on issues?

Yes

Has this been requested on Canny?

No

Motivation

At our company we are currently using docusaurus as a poc. We have lots of documents from prior flat file cms systems. Our problem is, that in order to compile successfully we have to go through every build step, catch errors found in the md files and remove them afterwards. This is currently done recursively because each "build step" yields different categories of errors. This increases the consumed time of our CI pipelines which is not optimal. To catch these faulty files via regex queries in the console output is also not the neatest way of handling this. Some faulty files are repairable easily, for example broken img links can just be removed. This is still tedious to do it for every bug so we decided to just delete them.

API Design

We now need a way of finding out whats wrong with our documents before building. Currently investigating different md linters for that, but maybe this could also be built into saurus? ex. cli tool for scanning a file which automatically removes lines which it cant compile, proceeds to the next build step and outputs the errors of the different error "hierarchies"/ categories. And if the linter doesnt catch our problems a way in which the compiler ignores/moves/removes these documents so it can build in ONE go would be really helpful.

Have you tried building it?

As i said currently we can only catch these errors via recursive building and removing the whole files. I also tried to look into the packages that scan/ compile these files but i felt that the code was spread on different packages which made it harder to find all aspects which docusaurus is using to compile.

We are ready to build this for you/ cooperate if you think its a necessary/ good feature.

[slorber]

I'm not sure to understand what you mean by "recursively compile" and "build steps".

We don't have a good way to detect errors early in the build process, and some errors are actually only reported by our own tooling (ie Webpack / Node.js reporting broken paths).

Detecting broken things asap is definitively something we should improve so that users have a quick feedback loop, but we are not there yet.

What I understand is that you'd like a "fail-safe" mode: you prefer deploying a broken Docusaurus site (with console warnings so that you are aware of the problems) rather than failing the CI build.

Here I'll need an exhaustive list of the distinct errors you encounter in practice, and the expected output of such a fail-safe behavior for each error.

An example:

If a .md document is not valid markdown/MDX, then I prefer to have the site render an empty page rather failing

(I'll be on holiday so I'll likely answer in a few weeks)

[000user]

Thanks for your answer! I'll attach some code we currently use to rerun the build process when im in office on monday. Additionally i'll append some console logs that identify the errors.

"Here I'll need an exhaustive list of the distinct errors you encounter in practice, and the expected output of such a fail-safe behavior for each error."
Yeah it could be done like this and as a result we could have a config to tell what to do with the specific errors ... eg: "throw/warn/error/remove"
But i guess some errors are so crucial that you cant continue the compilation process with the file so you'd have to delete it

But nevertheless a single switch which just deletes the faulty file and logs it would be the easiest solution, because when the 3rd party packages are updated they might introduce new code scanning methods which may lead to new error categories and we'd have to maintain a list of probable errors which seems to be time consuming. I think its also the easiest to implement the single switch method.

[000user]

mdErrors.txt
deleteFaultyMds.py.txt

Here is the script we currently use to build docusaurus. Yes its extremly crude and not very error tolerant but it just represents a POC. The most important method is the following

in this method the build process is executed and depending on the returned observed error from the logs, a different
removal process is executed and the method is run again.

In the attached file, i appended some markdown text and the resulting error logs. They are sorted in the sequence they occur. I didnt attach them, but missing image links also cause the build to fail.

As a solution instead of just deleting the faulty file there ofc are many other solutions like:
-displaying and empty file
-displaying and empty file with just the error log output
-display the page with errors (probably not possible because the different packages which build and
optimize the page consecutive require a clean state in order to pack and bundle the file correctly?)

[Josh-Cena]

I have a similar problem where the Crowdin auto translations are problematic. E.g. Make sure to save your <0>chart layout</0> on Tradingview after successfully installing an update so you can ensure it will stay becomes Assurez-vous d'enregistrer votre mise en page</0> <0>sur Tradingview après avoir installé avec succès une mise à jour afin de vous assurer qu'elle restera. (Notice the misplaced <0> tags) I have no idea why it does that since the order of words didn't even change much, but I ended up having a lot of tags being in the wrong place. While I can fix the French translation myself, I'm pretty clueless about other languages like German, so it would be cool if we can catch the page build errors and have some fallback (e.g. for i18n, fall back to base locale; for other cases, display a dedicated "something went wrong" page), while we look for translation contributors to inspect the issue.

[slorber]

Not sure how easy it would be to design such a feature.

In its current state, it may be hard to provide a fallback in case of SSR failures, because when the Webpack static generation plugin kicks in, the Webpack app probably already compiled, and the MDX has already been transformed to the final JSX.

There are some errors that we can catch at Webpack compilation/transpilation (including mdx->jsx), but others that only happen later in the process, when executing the code.

[000user]

regarding my problem - wouldnt it be the easiest to just implement a "force" build mode in which it excludes problematic files after each step? Like in my script but without the need to rerun the whole build process. And if the files are already indexed in some minified packed js file they ofc need to be removed/excluded from there too (maybe keep the sitebar entries but forbid navigation to the file and show a tooltip).

[slorber]

We can only implement a "force" build mode if we are able to design it, including potential edge cases, and that seems difficult to design. If you can write a formal spec of how it should behave exactly, we may be able to implement it, but that seems hard to write that spec in the first place.

If you have problematic files in your system, I suggest that you build your own tooling to detect these problems ahead of time and do whatever you want, and only run Docusaurus build once you are pretty sure all the problems were fixed

[slorber]

MDX v2 (Docusaurus v3) comes with a CommonMark compatible mode, which should throw much less errors compared to MDX regular compilation format.

CommonMark is much more fail-safe, and able to ignore things that seem invalid, like unclosed html/JSX:

I'm going to close assuming this is enough.

Useful links:

• CommonMark support RFC: RFC: CommonMark compatibility, supporting multiple markdown/content parsers #3018
• Some current limits: RFC: CommonMark compatibility, supporting multiple markdown/content parsers #3018
• MDX v2 PR: feat: upgrade to MDX v2 #8288