feat(v2): warn user when there are conflicting routes

[teikjun]

Motivation

Users may accidentally create conflicting routes. This is especially common when the user enables docs-only mode or blog-only mode. This PR adds a warning to inform the user that there are overriding paths when they run yarn start or yarn build. It also adds documentation that explains the warning.

This PR closes #3041.

Have you read the Contributing Guidelines on pull requests?

Yes

Test Plan

1. In docusaurus.config.js of D2 website, add a line routeBasePath: '/', to the docs-plugin section (line 116).
2. Run yarn start. There should be 3 warnings.

[docusaurus-bot]

Deploy preview for docusaurus-2 ready!

Built with commit 04587de

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

[slorber]

Tested and it seems to work fine.

However, can you make an implementation where detecting the bad routes is decorrelated from the effect (logging/throwing).

This way you can make the code more testable, and you'd be able to add tests easily on the most important parts.

Can you rework this PR, keeping the same behavior for now, and making the effect configurable with a onDuplicatePaths setting or something?

You can get inspiration from here, as the broken links detection behavior is quite similar to this
https://github.com/facebook/docusaurus/pull/3059/files#diff-e6be3562ac400435b5f35aa3276065b4R1

[slorber]

Also I think we should extract a helper for this fn. This kind of logic is used 3 times

(also used in a different form in loadRoutes to get the routePaths)

[slorber]

FYI, just remember this code in docs plugin. Maybe we should remove it or this plugin won't report the docs/home conflict correctly?

    async routesLoaded(routes) {
      const homeDocsRoutes = routes.filter(
        (routeConfig) => routeConfig.path === homePageDocsRoutePath,
      );

      // Remove the route for docs home page if there is a page with the same path (i.e. docs).
      if (homeDocsRoutes.length > 1) {
        const docsHomePageRouteIndex = routes.findIndex(
          (route) =>
            route.component === options.docLayoutComponent &&
            route.path === homePageDocsRoutePath,
        );

        delete routes[docsHomePageRouteIndex!];
      }
    },

[teikjun]

FYI, just remember this code in docs plugin. Maybe we should remove it or this plugin won't report the docs/home conflict correctly?

Ah I was just thinking about this, wasn't sure if this code was still needed. Ok, I'll just remove this code in docs plugin 👌

The warning is reported before the routesLoaded lifecycle, so I think the user should still get the correct warning in either case.

[teikjun]

I've completed the requested changes :D

[slorber]

That looks nice to me, just a few minor changes

[teikjun]

I think this could be used for reporting things other than errors, so I named it in a general way.
I also prepended the type of message (info, warn, error) in front of the body so it looks similar to the other messages that we see in the cli (I've updated the screenshot in the original post)

[slorber]

yes that looks fine

[teikjun]

Ready for review! :)

[slorber]

great work, thanks :)

Works well on D2 site if I use docs only mode