fix(v2): do not create route for document that serve as docs home page (#2861)

packages/docusaurus-plugin-content-docs/src/__tests__/__snapshots__/index.test.ts.snap

@@ -29,7 +29,7 @@ Object {
           "type": "link",
         },
         Object {
-          "href": "/docs/hello",
+          "href": "/docs",
           "label": "Hello, World !",
           "type": "link",
         },
@@ -41,7 +41,7 @@ Object {
       "collapsed": true,
       "items": Array [
         Object {
-          "href": "/docs/hello",
+          "href": "/docs",
           "label": "Hello, World !",
           "type": "link",
         },
@@ -88,14 +88,6 @@ Array [
         },
         "path": "/docs/foo/bazSlug.html",
       },
-      Object {
-        "component": "@theme/DocItem",
-        "exact": true,
-        "modules": Object {
-          "content": "@site/docs/hello.md",
-        },
-        "path": "/docs/hello",
-      },
       Object {
         "component": "@theme/DocItem",
         "exact": true,
@@ -170,14 +162,6 @@ Array [
         },
         "path": "/docs/1.0.0/foo/baz",
       },
-      Object {
-        "component": "@theme/DocItem",
-        "exact": true,
-        "modules": Object {
-          "content": "@site/versioned_docs/version-1.0.0/hello.md",
-        },
-        "path": "/docs/1.0.0/hello",
-      },
     ],
   },
   Object {
@@ -196,14 +180,6 @@ Array [
         },
         "path": "/docs/next/foo/barSlug",
       },
-      Object {
-        "component": "@theme/DocItem",
-        "exact": true,
-        "modules": Object {
-          "content": "@site/docs/hello.md",
-        },
-        "path": "/docs/next/hello",
-      },
     ],
   },
   Object {
@@ -222,14 +198,6 @@ Array [
         },
         "path": "/docs/foo/bar",
       },
-      Object {
-        "component": "@theme/DocItem",
-        "exact": true,
-        "modules": Object {
-          "content": "@site/versioned_docs/version-1.0.1/hello.md",
-        },
-        "path": "/docs/hello",
-      },
     ],
   },
 ]
@@ -254,7 +222,7 @@ Object {
       "collapsed": true,
       "items": Array [
         Object {
-          "href": "/docs/next/hello",
+          "href": "/docs/next",
           "label": "hello",
           "type": "link",
         },
@@ -285,7 +253,7 @@ Object {
       "collapsed": true,
       "items": Array [
         Object {
-          "href": "/docs/1.0.0/hello",
+          "href": "/docs/1.0.0",
           "label": "hello",
           "type": "link",
         },
@@ -311,7 +279,7 @@ Object {
       "collapsed": true,
       "items": Array [
         Object {
-          "href": "/docs/hello",
+          "href": "/docs",
           "label": "hello",
           "type": "link",
         },
@@ -348,7 +316,7 @@ Object {
         "collapsed": true,
         "items": Array [
           Object {
-            "href": "/docs/1.0.0/hello",
+            "href": "/docs/1.0.0",
             "label": "hello",
             "type": "link",
           },
@@ -387,7 +355,7 @@ Object {
         "collapsed": true,
         "items": Array [
           Object {
-            "href": "/docs/hello",
+            "href": "/docs",
             "label": "hello",
             "type": "link",
           },
@@ -425,7 +393,7 @@ Object {
         "collapsed": true,
         "items": Array [
           Object {
-            "href": "/docs/next/hello",
+            "href": "/docs/next",
             "label": "hello",
             "type": "link",
           },

packages/docusaurus-plugin-content-docs/src/index.ts

@@ -70,8 +70,6 @@ export default function pluginContentDocs(
   opts: Partial<PluginOptions>,
 ): Plugin<LoadedContent | null> {
   const options = {...DEFAULT_OPTIONS, ...opts};
-  const homePageDocsRoutePath =
-    options.routeBasePath === '' ? '/' : options.routeBasePath;
 
   if (options.admonitions) {
     options.remarkPlugins = options.remarkPlugins.concat([
@@ -98,6 +96,24 @@ export default function pluginContentDocs(
   } = versioning;
   const versionsNames = versions.map((version) => `version-${version}`);
 
+  // Docs home page.
+  const homePageDocsRoutePath =
+    options.routeBasePath === '' ? '/' : options.routeBasePath;
+  const isDocsHomePagePath = (permalink: string) => {
+    const documentIdMatch = new RegExp(
+      `^\/(?:${homePageDocsRoutePath}\/)?(?:(?:${versions.join(
+        '|',
+      )}|next)\/)?(.*)`,
+      'i',
+    ).exec(permalink);
+
+    if (documentIdMatch) {
+      return documentIdMatch[1] === options.homePageId;
+    }
+
+    return false;
+  };
+
   return {
     name: 'docusaurus-plugin-content-docs',
 
@@ -268,10 +284,14 @@ export default function pluginContentDocs(
           );
         }
 
+        const {title, permalink, sidebar_label} = linkMetadata;
+
         return {
           type: 'link',
-          label: linkMetadata.sidebar_label || linkMetadata.title,
+          label: sidebar_label || title,
-          href: linkMetadata.permalink,
+          href: isDocsHomePagePath(permalink)
+            ? permalink.replace(`/${options.homePageId}`, '')
+            : permalink,
         };
       };
 
@@ -361,7 +381,6 @@ export default function pluginContentDocs(
                 baseUrl,
                 homePageDocsRoutePath,
                 versionDocsPathPrefix,
-                options.homePageId,
               ]);
               const docsBaseMetadataPath = await createData(
                 `${docuHash(metadataItem.source)}-base.json`,
@@ -404,12 +423,9 @@ export default function pluginContentDocs(
 
         return (
           routes
-            // Do not create a route for a page created specifically for docs home page.
+            // Do not create a route for a document serve as docs home page.
-            .filter(
+            // TODO: need way to do this filtering when generating routes for better perf.
-              ({path}) =>
+            .filter(({path}) => !isDocsHomePagePath(path))
-                path.substr(path.lastIndexOf('/') + 1) !==
-                REVERSED_DOCS_HOME_PAGE_ID,
-            )
             .sort((a, b) => (a.path > b.path ? 1 : b.path > a.path ? -1 : 0))
         );
       };

website/docs/docs.md

@@ -61,7 +61,7 @@ module.exports = {
 };
 ```
 
-Given the example above, now when you navigate to the path `/docs` you will see that the document content with id is `getting-started`. This functionality also works for docs with versioning enabled.
+Given the example above, now when you navigate to the path `/docs` you will see that the document content with id is `getting-started`. This functionality also works for docs with versioning enabled. Importantly, with document serves as home docs page, it will not be available at its URL. Following the example above, this means that the `docs/getting-started` URL will be lead to a 404 error.
 
 :::important