feat: Plugin error handling

[jhildenbiddle]

Summary

Fix #1741 (see for details)

What kind of change does this PR introduce?

• Add new catchPluginErrors configuration option to enable/disable handling uncaught plugin errors (default: true). This feature prevents uncaught plugin errors from halting JavaScript execution and breaking Docsify sites.
• Add e2e tests for catchPluginErrors configuration option
• Add e2e tests for all plugin hooks (data handling and invocation order)
• Update Write a Plugin new new Setup, Template, Lifecycle Hooks, and Tips sections (see Vercel preview below)

Screenshots

Assuming the following plugin code:

window.$docsify = {
  // ...
  plugins: [
    function (hook, vm) {
      hook.beforeEach(function (content) {
        console.log('Plugin 1');
        console.log(['fail', 'success'].at(1)); // <= ERROR: at() not supported by Safari
      });
    },
    function (hook, vm) {
      hook.beforeEach(function (content) {
        console.log('Plugin 2');
        console.log(['fail', 'success'][1]);
      });
    }
  ]
}

Before

Safari 15.3: Uncaught "Plugin 1" error halts JavaScript execution, breaking docsify site.

After

Safari 15.3 w/ catchPluginErrors: true (default): Uncaught "Plugin 1" error is caught by docsify and logged to the console, allowing Docsify to continue with "Plugin 2" and rendering site content.

Note that error details are provided in the console as they were before. Site owners and plugin authors that use the console to troubleshoot and debug can continue to do so. Safari collapses these details by default. Chrome does not.

Safari 15.3 w/ catchPluginErrors: false: Same as "Before".

For any code change,

• Related documentation has been updated if needed
• Related tests have been updated or tests have been added

Does this PR introduce a breaking change? (check one)

• Yes
• No

If yes, please describe the impact and migration path for existing applications:

Related issue, if any:

#1741
#1209

Tested in the following browsers:

• Chrome
• Firefox
• Safari
• Edge
• IE

[vercel]

This pull request is being automatically deployed with Vercel (learn more).
To see the status of your deployment, click below or on the icon next to each commit.

🔍 Inspect: https://vercel.com/docsify-core/docsify-preview/CdsP8nNhoRDzC6NAqWZAPvGxFH4i
✅ Preview: https://docsify-preview-git-plugin-error-handling-docsify-core.vercel.app

[codesandbox-ci]

This pull request is automatically built and testable in CodeSandbox.

To see build info of the built libraries, click here or the icon next to each commit SHA.

Latest deployment of this branch, based on commit 650870c:

Sandbox	Source
docsify-template	Configuration

[trusktr]

Is the error navigable the same way as an uncaught error, in console?

Now that errors are caught, they will not be pausable by default in debugger, and the pause on caught errors option generally pauses too much that it can become inconvenient.

Personally I would prefer to see my actual errors in console, and in the console I can clearly see which plugin I wrote bad code in.

The error stack trace of an error that is shown in console tells us exactly where the error came from (hence we already know if it comes from a plugin)

[jhildenbiddle]

@trusktr --

Details available in #1741...

Is the error navigable the same way as an uncaught error, in console?

Yes.

Now that errors are caught, they will not be pausable by default in debugger, and the pause on caught errors option generally pauses too much that it can become inconvenient.

Personally I would prefer to see my actual errors in console, and in the console I can clearly see which plugin I wrote bad code in.

Set catchPluginErrors to false during plugin development if you wish to use a debugger as you do today.

The error stack trace of an error that is shown in console tells us exactly where the error came from (hence we already know if it comes from a plugin)

Still there. See screenshots above or in #1741.

[Koooooo-7]

should we console all hooks directly or we should have a switch to open this console output? i.e.
debugEnable: true.

[jhildenbiddle]

@Koooooo-7 --

should we console all hooks directly or we should have a switch to open this console output? i.e.debugEnable: true.

I'm not sure I understand the question. It sounds like you're asking if we should add a new configuration option that either A) prevents uncaught plugin errors from being displayed in the console or B) opens the console automatically when an error occurs (presumably to make people aware that the error occurred).

I don't think we should consider either option.

For option "A": Errors should continue to be sent to the console as they are today because the console is where developers and end-users expect to find error-related details. This PR does not change that, and that is by design. Developers and end-users that use the console to debug and/or troubleshoot can continue to do so exactly as they do today. Site visitors that don't know or care about the console are free to ignore it exactly as they do today.

It's worth mentioning that if a plugin author or end user really wanted to suppress error messages in the console, they can do so already by implementing their own try/catch block(s) and/or using the console message filters provided by the browser:

Chrome 99

Safari 15.3

For option "B": I don't think it is possible to programmatically open the browser console, but even if was we should not assume that every site visitor 4) needs to be notified that a plugin error has occurred, 2) knows what the console is, 3) will understand why the console is being displayed, or 4) knows how to dismiss the console. The console is there for the people that need it, but it is not intended to be used as a general-purpose notification tool.

All that being said, your question does hint at two separate-but-related topics:

1. How will people know when an error has occurred if the console isn't open?
2. What should happen when an error occurs?

These are valid questions, but I believe they are outside the scope of this PR. If we want to address them, let's create a new issue where we can discuss the details. I have some ideas regarding a new error-related hook that would address both of these concerns and provide some interesting plugin opportunities.

In the meantime, my hope is that we can merge this PR and discuss other plugin-related enhancements elsewhere.

Thanks!

[Koooooo-7]

LGTM.

[sy-records]

LGTM.

Thank you for your contribution.

[jhildenbiddle]

Thanks @Koooooo-7 and @sy-records for the review! 🥳