Docusaurus: Can no longer remove /docs from the URL since v59

[Dannyholt]

🐛 Bug Report

Before v59 we were able to remove /docs from the URL by setting routeBasePath: '', whilst still being able to use pages see #2713. However, as of v59 routeBasePath can no longer be empty and adding a / to routeBasePath forces docs-only mode and therefore, no pages. This results in nav items to 404. :(

To Reproduce

1. Use a landing page.
2. Add your nav items like this:

items: [
  {
    to: '/getting-started',
    label: 'Getting Started',
    position: 'left',
    activeBasePath: 'getting-started',
  },

1. Set routeBasePath to '' or '/'
2. Visit your site and all nav items except the logo will now 404.

Expected behavior

You should be able to remove /docs from the URL without having to use docs-only mode. We really wanted to update so we can use the DocSearch v3, but this is going to prevent us from doing so. :(

Your Environment

• Docusaurus version used: 2.0.0-alpha.59

Reproducible Demo

N/A

[teikjun]

Thanks! #3120 adds empty string '' to the list of accepted values for routeBasePath.

[slorber]

@Dannyholt , as far as I understand, you want docs to be at the root path, yet being able to provide custom pages also under "/".

Actually we had some important refactors on how docs are handled, as they were quite a few bugs, but we should support this usecase and will probably release a fix soon.

Can you confirm this only affect your homepage? or do you see other pages for which this is a problem?

---

@teikjun this is not related to the '' value specifically, but to this code that removes the homepage in particulary:

    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!];
      }
    },

Anyway as we already planned to remove that code, it should be fixed for the next release.

[Dannyholt]

@slorber

I mentioned this in Discord, but thought i'd mention it here anyway. It actually didn't cause any issue with the homepage or other custom pages as they worked as intended. The issue was the nav items in the header no longer worked went to the doc articles and instead caused a 404.

[slorber]

Hey, this is fixed in https://github.com/facebook/docusaurus/pull/3141

will be released soon, probably tomorrow

[slorber]

released in https://github.com/facebook/docusaurus/releases/tag/v2.0.0-alpha.60

can you tell me if it works?

[Dannyholt]

@slorber

Yes issue is now resolved. Thanks!

[slorber]

Hey,

I think accepting '' as a value was a bad idea that actually lead to errors later, but still think that '/' should work for your usecase. Please tell me if you think you can't use '/' instead, because '' will be rejected in alpha 63.

https://github.com/facebook/docusaurus/pull/3375