Improve docs navbar items error messages

[slorber]

Have you read the Contributing Guidelines on issues?

• I have read the Contributing Guidelines on issues.

Motivation

The navbar error messages are not so great and some new users get confused when they encounter an error trying to modify a newly initialized Docusaurus project.

I think we should improve these error messages so that users understand what to do:

cf #8692

Also we could introduce a new docSidebar navbar item that links to a given sidebar. This is less likely to lead users to encounter errors when trying Docusaurus for the first time because they are less likely to delete/rename a sidebar IMHO.

The init template has an tutorialSidebar autogenerated sidebar: https://github.com/facebook/docusaurus/blob/main/examples/classic/sidebars.js

I suggest moving the init template from:

navbar: {
        items: [
          {
            type: 'doc',
            docId: 'intro',
            position: 'left',
            label: 'Tutorial',
          },
        ],
      },

to

navbar: {
        items: [
          {
            type: 'docSidebar',
            sidebarName: 'tutorialSidebar',
            position: 'left',
            label: 'Tutorial',
          },
        ],
      },

---

Good first issue for an external contributor that feels comfortable taking this task.

You can claim the issue here, but please submit a first draft PR within 24h.
Otherwise, someone else can claim it again and submit a new PR.

Self-service

• I'd be willing to do some initial work on this proposal myself.

[useCallback]

how should the error message look like ?

[useCallback]

I'd like to work on this

[slorber]

Thanks @KhalfounMehdi , go ahead and submit a PR, we'll discuss the exact wording on the PR directly

how should the error message look like ?

I don't know the exact wording we should use but it should help user figure out that the problem is in the Docusaurus config file, in one of the themeConfig.navbar.items items. Try to do your best to make the error helpful to users.

Considering the error message is thrown in a quite generic hook (used in multiple places), there are a few options we could use to improve the DX:

• use the new JS error cause feature to enrich the initial error with extra contextual info: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/cause
• maybe add a React error boundary around the failing navbar item, and do not crash the app in case of error but show a red square or something?
• do both: error boundary to avoid crashing the app, but good console error message to read with more context

Using error cause can probably be done this way inside DocNavbarItem:

function useNavbarItemDoc(docId, docsPluginId) {
  try {
    return useLayoutDoc(docId, docsPluginId);
  } catch (e) {
    throw new Error(
      "There's a problem in a navbar item blabla, your Docusaurus config themeConfig.navbar.items is probably wrong blabla...",
      { cause: e }
    );
  }
}

Note: other navbar items might be affected by similarly unclear error messages as well: let's fix them all if possible!

[tannerdolby]

👋 @slorber I've started tinkering on this locally based on your notes above, I see @KhalfounMehdi has first dibs but if there isn't a PR submitted in the next few days I'm happy to submit one!

[slorber]

@tannerdolby feel free to work on it.

You can claim the issue here, but please submit a first draft PR within 24h.
Otherwise, someone else can claim it again and submit a new PR.

The first to open a draft PR showing they are actually working on this will be assigned the issue.

[slorber]

Just figured out we already have a docSidebar navbar item type and there's already a PR proposing to change the type in our init templates here: #8712

Improving the error messages remain a thing we should do, so another PR focusing on that is welcome.

[tannerdolby]

Okay sounds good! Thanks for the heads up. I will submit a PR that focuses on improving the error messages.

[slorber]

Fixed by #8712 and #8735