Page Error Handling

[ByronMayne]

Hey folks,

I am using Docusaurus a bit of a unique way at my company. We ship the whole development environment onto the end users machine. We then start the application with the development server. This is done because we have a package manager that is currently used by 1000+ daily active users. These packages that are created can optional contain a documentation folder.

The problem I currently have is we have over just over 1200 packages and the docs are sometimes broken. They should be fixed, however I would like to be able to support handling this more graceful. Rather then having the website blow up, replace the broken page with an error message listing the compiler errors.

Can there a way to do this elegantly?

Just as a side note, this project is awesome and really appreciate all the work you folks have been putting into it.

[slorber]

Thanks @ByronMayne

It's hard for me to understand what is means for docs to be broken, and what you mean by compiler errors.

Can you create a runnable docusaurus.new sandbox that is representative of the case you encounter, by providing actual broken doc content, and being able to see the non-graceful errors you user see?

[ByronMayne]

Thanks for getting back to me!

A very common issue is not having escaped '<' and '{' in MDX pages. This happens all the time now with the upgrade to version 3.

When the MDXLoader for webpack runs, it fails to compile and returns an error to webpack. If a visitor attempts to access that invalid page, the webpage crashex and the webpack red overlay shows. If they dismiss the overlay or its disabled the whole website is missing, it's just an empty white browser page.

What I was hoping to do was instead of just erroring and crashing the page to instead fallback on the loader returning an html page that contains the webpack errors. This way the website is still useable.

It's important to note this is all happening when running the development server.

I am a C# developer by trade but being doing more and more JS development recently, so my terminology might be incorrect. I have spent the whole day yesterday stepping through trying to figure out how it worked.

I will put together a sample project when I get to work today 😄

[slorber]

Hey

MDX compiles Markdown to React components, so technically if we can't generate a React component for pages and blogs it's hard to display anything.

What you are asking looks like:

function toJSXString(mdString) {
  try {
    return mdxCompile(mdString);
  } catch (e) {
    return `<div>{e.message}</div>`
  }
}

I don't think it's a good idea to do so, because most users will want errors displayed in the dev server stead of this fallback ui, and this will also not fail-fast in case of compilation errors n both dev and prod. We don't want to let site builds and silently succeed despite errors, and those errors should also be surfaced at dev time so that if it works in dev it is likely to work in prod build too.

---

Unless there are clear strong arguments + multiple community requests + a full retrocompatible feature design, I doubt we ever implement this. It's not reasonable to implement this just for your custom need IMHO.

My suggestions:

• give a try the commonmark mode, much less likely to error: https://docusaurus.io/docs/markdown-features/react#markdown-and-jsx-interoperability
• use patch-package to modify Docusaurus for your project and implement this try/catch logic yourself in the mdx loader

[ByronMayne]

Oh of course, I would not expect you folks to fix this issue! I put it in discussions just looking to get some guidance on how you think I could attempt to do it. We have dozens of teams writing docs and we can't update to v3 because of these new errors. So just looking to do some sort of patch fix :)

This is an example of what happens

The content of this mdx files is just

# Unescaped Page

Generic<T>

Ideally I would love to get it to do something like this instead

Thank you for taking the time to answer my questions, I really appreciate it.

I am thinking of adding a callback like already exists for the preprocessor.

{
  markdown: {
     errorHandler: (args: { filePath:string, fileContent:string, error:Error}) => {
         return <div> ERROR :( </div> 
     }
  }
}

[ByronMayne]

For anyone else in the future:

I ended up create an instance of the parser, and just manually running it as pre-validation. I originally attempted to put this inside of the markdown.preprocessor callback, however this does not work because the compiler is async and the callback is sync.

Because I am already copying around the markdown files into the local directory, I run the compiler and fallback on error page when it fails.

import { createProcessorCached } from "@docusaurus/mdx-loader/lib/processor";
import { Options as LoaderOptions } from "@docusaurus/mdx-loader"
import { MarkdownConfig } from "@docusaurus/types";
import { fileReadAsync, fileWriteAsync } from "./io";

const markdownPreprocessor = async (config: MarkdownConfig, filePath: string): Promise<boolean> => {

    const processor = await createProcessorCached({
        filePath: filePath,
        query: "",
        mdxFrontMatter: {
            format: 'detect'
        },
        reqOptions: {
            admonitions: true,
            markdownConfig: {
                format: config.format,
                mdx1Compat: {
                    comments: true,
                    admonitions: true,
                    headingIds: true,
                },
                mermaid: config.mermaid,
            }
        } as LoaderOptions
    });

    try {

        const content:string = await fileReadAsync(filePath);

        // Attempt to parse, if it fails just return an error
        await processor.process({
            content: content,
            filePath: filePath,
            compilerName: 'server',
            frontMatter: {}
        })
        return true;
        // it's valid 
    } catch (error: any) {

        await fileWriteAsync(filePath,`
            :::danger Compiler Error
                The documentation failed to compile due to the following errors.
                \`\`\`log 
                    ${error}
                \`\`\`
            :::`);
        return false;
    }
}

[slorber]

not sure your solution is super reliable, but that probably makes sense to allow the preprocessor callback to be async

[ByronMayne]

Yeah it's for sure not the greatest, but it required the least amount of divergence. With this I can capture most of the errors and replace it with this. I will most likely be adjusting it over time

Thanks for your help :)