From 6734005f5c441756651d248b0f8c6afa79d2a566 Mon Sep 17 00:00:00 2001
From: slorber <lorber.sebastien@gmail.com>
Date: Mon, 8 Jun 2020 17:00:04 +0200
Subject: [PATCH 01/16] better fixes for docs homepage

---
 .../src/index.ts                              | 42 ++++---------------
 .../src/metadata.ts                           | 26 +++++++++---
 .../src/types.ts                              |  3 +-
 .../src/theme/DocPage/index.js                |  4 --
 .../src/theme/DocSidebar/index.js             |  8 +++-
 5 files changed, 37 insertions(+), 46 deletions(-)

diff --git a/packages/docusaurus-plugin-content-docs/src/index.ts b/packages/docusaurus-plugin-content-docs/src/index.ts
index 4459e295e573..c89e52e2efb2 100644
--- a/packages/docusaurus-plugin-content-docs/src/index.ts
+++ b/packages/docusaurus-plugin-content-docs/src/index.ts
@@ -69,7 +69,9 @@ export default function pluginContentDocs(
   context: LoadContext,
   opts: Partial<PluginOptions>,
 ): Plugin<LoadedContent | null> {
-  const options = {...DEFAULT_OPTIONS, ...opts};
+  const options: PluginOptions = {...DEFAULT_OPTIONS, ...opts};
+  const homePageDocsRoutePath =
+    options.routeBasePath === '' ? '/' : options.routeBasePath;
 
   if (options.admonitions) {
     options.remarkPlugins = options.remarkPlugins.concat([
@@ -96,24 +98,6 @@ 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',
 
@@ -291,9 +275,7 @@ Available document ids=
         return {
           type: 'link',
           label: sidebar_label || title,
-          href: isDocsHomePagePath(permalink)
-            ? permalink.replace(`/${options.homePageId}`, '')
-            : permalink,
+          href: permalink,
         };
       };
 
@@ -361,15 +343,9 @@ Available document ids=
       const genRoutes = async (
         metadataItems: Metadata[],
       ): Promise<RouteConfig[]> => {
-        const versionsRegex = new RegExp(versionsNames.join('|'), 'i');
-
         const routes = await Promise.all(
           metadataItems.map(async (metadataItem) => {
-            const isDocsHomePage =
-              metadataItem.id.replace(versionsRegex, '').replace(/^\//, '') ===
-              options.homePageId;
-
-            if (isDocsHomePage) {
+            if (metadataItem.isDocsHomePage) {
               const versionDocsPathPrefix =
                 (metadataItem?.version === versioning.latestVersion
                   ? ''
@@ -423,12 +399,8 @@ Available document ids=
           }),
         );
 
-        return (
-          routes
-            // Do not create a route for a document serve as docs home page.
-            // TODO: need way to do this filtering when generating routes for better perf.
-            .filter(({path}) => !isDocsHomePagePath(path))
-            .sort((a, b) => (a.path > b.path ? 1 : b.path > a.path ? -1 : 0))
+        return routes.sort((a, b) =>
+          a.path > b.path ? 1 : b.path > a.path ? -1 : 0,
         );
       };
 
diff --git a/packages/docusaurus-plugin-content-docs/src/metadata.ts b/packages/docusaurus-plugin-content-docs/src/metadata.ts
index 66225d8918aa..9033cc516fa2 100644
--- a/packages/docusaurus-plugin-content-docs/src/metadata.ts
+++ b/packages/docusaurus-plugin-content-docs/src/metadata.ts
@@ -59,7 +59,7 @@ export default async function processMetadata({
   options,
   env,
 }: Args): Promise<MetadataRaw> {
-  const {routeBasePath, editUrl} = options;
+  const {routeBasePath, editUrl, homePageId} = options;
   const {siteDir, baseUrl} = context;
   const {versioning} = env;
   const filePath = path.join(refDir, source);
@@ -101,6 +101,14 @@ export default async function processMetadata({
     throw new Error('Document id cannot include "/".');
   }
 
+  const isDocsHomePage = homePageId === baseID;
+
+  if (frontMatter.slug && isDocsHomePage) {
+    throw new Error(
+      `The docs homepage (homePageId=${homePageId}) is not allowed to have a frontmatter slug=${frontMatter.slug} => you have to chooser either homePageId or slug, not both`,
+    );
+  }
+
   const baseSlug: string = frontMatter.slug || baseID;
   if (baseSlug.includes('/')) {
     throw new Error('Document slug cannot include "/".');
@@ -116,10 +124,17 @@ export default async function processMetadata({
   const description: string = frontMatter.description || excerpt;
 
   // The last portion of the url path. Eg: 'foo/bar', 'bar'.
-  const routePath =
-    version && version !== 'next'
-      ? slug.replace(new RegExp(`^version-${version}/`), '')
-      : slug;
+  let routePath;
+  if (isDocsHomePage) {
+    // TODO can we remove this trailing / ?
+    // Seems it's not that easy...
+    routePath = '/';
+  } else {
+    routePath =
+      version && version !== 'next'
+        ? slug.replace(new RegExp(`^version-${version}/`), '')
+        : slug;
+  }
 
   const permalink = normalizeUrl([
     baseUrl,
@@ -136,6 +151,7 @@ export default async function processMetadata({
   // class transitions.
   const metadata: MetadataRaw = {
     id,
+    isDocsHomePage,
     title,
     description,
     source: aliasedSitePath(filePath, siteDir),
diff --git a/packages/docusaurus-plugin-content-docs/src/types.ts b/packages/docusaurus-plugin-content-docs/src/types.ts
index d9c4608bbdeb..ae535d5b358f 100644
--- a/packages/docusaurus-plugin-content-docs/src/types.ts
+++ b/packages/docusaurus-plugin-content-docs/src/types.ts
@@ -7,6 +7,7 @@
 
 export interface MetadataOptions {
   routeBasePath: string;
+  homePageId: string;
   editUrl?: string;
   showLastUpdateTime?: boolean;
   showLastUpdateAuthor?: boolean;
@@ -24,7 +25,6 @@ export interface PluginOptions extends MetadataOptions, PathOptions {
   remarkPlugins: ([Function, object] | Function)[];
   rehypePlugins: string[];
   admonitions: any;
-  homePageId: string;
 }
 
 export type SidebarItemDoc = {
@@ -111,6 +111,7 @@ export interface LastUpdateData {
 
 export interface MetadataRaw extends LastUpdateData {
   id: string;
+  isDocsHomePage: boolean;
   title: string;
   description: string;
   source: string;
diff --git a/packages/docusaurus-theme-classic/src/theme/DocPage/index.js b/packages/docusaurus-theme-classic/src/theme/DocPage/index.js
index fe3ef2767d16..397fecd22784 100644
--- a/packages/docusaurus-theme-classic/src/theme/DocPage/index.js
+++ b/packages/docusaurus-theme-classic/src/theme/DocPage/index.js
@@ -44,10 +44,6 @@ function DocPage(props) {
     isClient,
   } = useDocusaurusContext();
 
-  if (isHomePage) {
-    content.metadata.permalink = homePagePath;
-  }
-
   if (!isHomePage && Object.keys(currentRoute).length === 0) {
     return <NotFound {...props} />;
   }
diff --git a/packages/docusaurus-theme-classic/src/theme/DocSidebar/index.js b/packages/docusaurus-theme-classic/src/theme/DocSidebar/index.js
index 68e710db040a..feb075b5fdbc 100644
--- a/packages/docusaurus-theme-classic/src/theme/DocSidebar/index.js
+++ b/packages/docusaurus-theme-classic/src/theme/DocSidebar/index.js
@@ -27,9 +27,15 @@ function usePrevious(value) {
   return ref.current;
 }
 
+// Compare the 2 paths, ignoring trailing /
+const isSamePath = (path1, path2) => {
+  const normalize = (str) => (str.endsWith('/') ? str : `${str}/`);
+  return normalize(path1) === normalize(path2);
+};
+
 const isActiveSidebarItem = (item, activePath) => {
   if (item.type === 'link') {
-    return item.href === activePath;
+    return isSamePath(item.href, activePath);
   }
   if (item.type === 'category') {
     return item.items.some((subItem) =>

From bfe01e231ad85a4475563c8cce9461c5f79273ee Mon Sep 17 00:00:00 2001
From: slorber <lorber.sebastien@gmail.com>
Date: Mon, 8 Jun 2020 17:18:02 +0200
Subject: [PATCH 02/16] fix tests

---
 .../__snapshots__/index.test.ts.snap          | 54 +++++++++++++++----
 .../src/__tests__/index.test.ts               | 16 ++++--
 .../src/__tests__/metadata.test.ts            | 12 +++++
 3 files changed, 66 insertions(+), 16 deletions(-)

diff --git a/packages/docusaurus-plugin-content-docs/src/__tests__/__snapshots__/index.test.ts.snap b/packages/docusaurus-plugin-content-docs/src/__tests__/__snapshots__/index.test.ts.snap
index 4b5e8694c369..c2df4e07d11c 100644
--- a/packages/docusaurus-plugin-content-docs/src/__tests__/__snapshots__/index.test.ts.snap
+++ b/packages/docusaurus-plugin-content-docs/src/__tests__/__snapshots__/index.test.ts.snap
@@ -29,7 +29,7 @@ Object {
           "type": "link",
         },
         Object {
-          "href": "/docs",
+          "href": "/docs/",
           "label": "Hello, World !",
           "type": "link",
         },
@@ -41,7 +41,7 @@ Object {
       "collapsed": true,
       "items": Array [
         Object {
-          "href": "/docs",
+          "href": "/docs/",
           "label": "Hello, World !",
           "type": "link",
         },
@@ -72,6 +72,14 @@ Array [
     "path": "/docs/:route",
     "priority": undefined,
     "routes": Array [
+      Object {
+        "component": "@theme/DocItem",
+        "exact": true,
+        "modules": Object {
+          "content": "@site/docs/hello.md",
+        },
+        "path": "/docs/",
+      },
       Object {
         "component": "@theme/DocItem",
         "exact": true,
@@ -156,6 +164,14 @@ Array [
     "path": "/docs/1.0.0/:route",
     "priority": undefined,
     "routes": Array [
+      Object {
+        "component": "@theme/DocItem",
+        "exact": true,
+        "modules": Object {
+          "content": "@site/versioned_docs/version-1.0.0/hello.md",
+        },
+        "path": "/docs/1.0.0/",
+      },
       Object {
         "component": "@theme/DocItem",
         "exact": true,
@@ -182,6 +198,14 @@ Array [
     "path": "/docs/next/:route",
     "priority": undefined,
     "routes": Array [
+      Object {
+        "component": "@theme/DocItem",
+        "exact": true,
+        "modules": Object {
+          "content": "@site/docs/hello.md",
+        },
+        "path": "/docs/next/",
+      },
       Object {
         "component": "@theme/DocItem",
         "exact": true,
@@ -200,6 +224,14 @@ Array [
     "path": "/docs/:route",
     "priority": -1,
     "routes": Array [
+      Object {
+        "component": "@theme/DocItem",
+        "exact": true,
+        "modules": Object {
+          "content": "@site/versioned_docs/version-1.0.1/hello.md",
+        },
+        "path": "/docs/",
+      },
       Object {
         "component": "@theme/DocItem",
         "exact": true,
@@ -232,7 +264,7 @@ Object {
       "collapsed": true,
       "items": Array [
         Object {
-          "href": "/docs/next",
+          "href": "/docs/next/",
           "label": "hello",
           "type": "link",
         },
@@ -263,7 +295,7 @@ Object {
       "collapsed": true,
       "items": Array [
         Object {
-          "href": "/docs/1.0.0",
+          "href": "/docs/1.0.0/",
           "label": "hello",
           "type": "link",
         },
@@ -289,7 +321,7 @@ Object {
       "collapsed": true,
       "items": Array [
         Object {
-          "href": "/docs",
+          "href": "/docs/",
           "label": "hello",
           "type": "link",
         },
@@ -326,7 +358,7 @@ Object {
         "collapsed": true,
         "items": Array [
           Object {
-            "href": "/docs/1.0.0",
+            "href": "/docs/1.0.0/",
             "label": "hello",
             "type": "link",
           },
@@ -337,9 +369,9 @@ Object {
     ],
   },
   "permalinkToSidebar": Object {
+    "/docs/1.0.0/": "version-1.0.0/docs",
     "/docs/1.0.0/foo/barSlug": "version-1.0.0/docs",
     "/docs/1.0.0/foo/baz": "version-1.0.0/docs",
-    "/docs/1.0.0/hello": "version-1.0.0/docs",
   },
   "version": "1.0.0",
 }
@@ -365,7 +397,7 @@ Object {
         "collapsed": true,
         "items": Array [
           Object {
-            "href": "/docs",
+            "href": "/docs/",
             "label": "hello",
             "type": "link",
           },
@@ -376,8 +408,8 @@ Object {
     ],
   },
   "permalinkToSidebar": Object {
+    "/docs/": "version-1.0.1/docs",
     "/docs/foo/bar": "version-1.0.1/docs",
-    "/docs/hello": "version-1.0.1/docs",
   },
   "version": "1.0.1",
 }
@@ -403,7 +435,7 @@ Object {
         "collapsed": true,
         "items": Array [
           Object {
-            "href": "/docs/next",
+            "href": "/docs/next/",
             "label": "hello",
             "type": "link",
           },
@@ -414,8 +446,8 @@ Object {
     ],
   },
   "permalinkToSidebar": Object {
+    "/docs/next/": "docs",
     "/docs/next/foo/barSlug": "docs",
-    "/docs/next/hello": "docs",
   },
   "version": "next",
 }
diff --git a/packages/docusaurus-plugin-content-docs/src/__tests__/index.test.ts b/packages/docusaurus-plugin-content-docs/src/__tests__/index.test.ts
index f95507c71ef6..0715ecb95b57 100644
--- a/packages/docusaurus-plugin-content-docs/src/__tests__/index.test.ts
+++ b/packages/docusaurus-plugin-content-docs/src/__tests__/index.test.ts
@@ -154,7 +154,8 @@ describe('simple website', () => {
     expect(versionToSidebars).toEqual({});
     expect(docsMetadata.hello).toEqual({
       id: 'hello',
-      permalink: '/docs/hello',
+      isDocsHomePage: true,
+      permalink: '/docs/',
       previous: {
         title: 'baz',
         permalink: '/docs/foo/bazSlug.html',
@@ -167,6 +168,7 @@ describe('simple website', () => {
 
     expect(docsMetadata['foo/bar']).toEqual({
       id: 'foo/bar',
+      isDocsHomePage: false,
       next: {
         title: 'baz',
         permalink: '/docs/foo/bazSlug.html',
@@ -294,6 +296,7 @@ describe('versioned website', () => {
     expect(docsMetadata['version-1.0.1/foo/baz']).toBeUndefined();
     expect(docsMetadata['foo/bar']).toEqual({
       id: 'foo/bar',
+      isDocsHomePage: false,
       permalink: '/docs/next/foo/barSlug',
       source: path.join('@site', routeBasePath, 'foo', 'bar.md'),
       title: 'bar',
@@ -302,12 +305,13 @@ describe('versioned website', () => {
       sidebar: 'docs',
       next: {
         title: 'hello',
-        permalink: '/docs/next/hello',
+        permalink: '/docs/next/',
       },
     });
     expect(docsMetadata['hello']).toEqual({
       id: 'hello',
-      permalink: '/docs/next/hello',
+      isDocsHomePage: true,
+      permalink: '/docs/next/',
       source: path.join('@site', routeBasePath, 'hello.md'),
       title: 'hello',
       description: 'Hello next !',
@@ -320,7 +324,8 @@ describe('versioned website', () => {
     });
     expect(docsMetadata['version-1.0.1/hello']).toEqual({
       id: 'version-1.0.1/hello',
-      permalink: '/docs/hello',
+      isDocsHomePage: true,
+      permalink: '/docs/',
       source: path.join(
         '@site',
         path.relative(siteDir, versionedDir),
@@ -338,6 +343,7 @@ describe('versioned website', () => {
     });
     expect(docsMetadata['version-1.0.0/foo/baz']).toEqual({
       id: 'version-1.0.0/foo/baz',
+      isDocsHomePage: false,
       permalink: '/docs/1.0.0/foo/baz',
       source: path.join(
         '@site',
@@ -353,7 +359,7 @@ describe('versioned website', () => {
       sidebar: 'version-1.0.0/docs',
       next: {
         title: 'hello',
-        permalink: '/docs/1.0.0/hello',
+        permalink: '/docs/1.0.0/',
       },
       previous: {
         title: 'bar',
diff --git a/packages/docusaurus-plugin-content-docs/src/__tests__/metadata.test.ts b/packages/docusaurus-plugin-content-docs/src/__tests__/metadata.test.ts
index 3f413199b824..2b50045d6c67 100644
--- a/packages/docusaurus-plugin-content-docs/src/__tests__/metadata.test.ts
+++ b/packages/docusaurus-plugin-content-docs/src/__tests__/metadata.test.ts
@@ -46,6 +46,7 @@ describe('simple site', () => {
 
     expect(dataA).toEqual({
       id: 'foo/bar',
+      isDocsHomePage: false,
       permalink: '/docs/foo/bar',
       source: path.join('@site', routeBasePath, sourceA),
       title: 'Bar',
@@ -53,6 +54,7 @@ describe('simple site', () => {
     });
     expect(dataB).toEqual({
       id: 'hello',
+      isDocsHomePage: false,
       permalink: '/docs/hello',
       source: path.join('@site', routeBasePath, sourceB),
       title: 'Hello, World !',
@@ -79,6 +81,7 @@ describe('simple site', () => {
 
     expect(data).toEqual({
       id: 'foo/baz',
+      isDocsHomePage: false,
       permalink: '/docs/foo/bazSlug.html',
       source: path.join('@site', routeBasePath, source),
       title: 'baz',
@@ -104,6 +107,7 @@ describe('simple site', () => {
 
     expect(data).toEqual({
       id: 'lorem',
+      isDocsHomePage: false,
       permalink: '/docs/lorem',
       source: path.join('@site', routeBasePath, source),
       title: 'lorem',
@@ -133,6 +137,7 @@ describe('simple site', () => {
 
     expect(data).toEqual({
       id: 'lorem',
+      isDocsHomePage: false,
       permalink: '/docs/lorem',
       source: path.join('@site', routeBasePath, source),
       title: 'lorem',
@@ -161,6 +166,7 @@ describe('simple site', () => {
 
     expect(data).toEqual({
       id: 'ipsum',
+      isDocsHomePage: false,
       permalink: '/docs/ipsum',
       source: path.join('@site', routeBasePath, source),
       title: 'ipsum',
@@ -244,6 +250,7 @@ describe('versioned site', () => {
 
     expect(dataA).toEqual({
       id: 'foo/bar',
+      isDocsHomePage: false,
       permalink: '/docs/next/foo/barSlug',
       source: path.join('@site', routeBasePath, sourceA),
       title: 'bar',
@@ -252,6 +259,7 @@ describe('versioned site', () => {
     });
     expect(dataB).toEqual({
       id: 'hello',
+      isDocsHomePage: false,
       permalink: '/docs/next/hello',
       source: path.join('@site', routeBasePath, sourceB),
       title: 'hello',
@@ -302,6 +310,7 @@ describe('versioned site', () => {
 
     expect(dataA).toEqual({
       id: 'version-1.0.0/foo/bar',
+      isDocsHomePage: false,
       permalink: '/docs/1.0.0/foo/barSlug',
       source: path.join('@site', path.relative(siteDir, versionedDir), sourceA),
       title: 'bar',
@@ -310,6 +319,7 @@ describe('versioned site', () => {
     });
     expect(dataB).toEqual({
       id: 'version-1.0.0/hello',
+      isDocsHomePage: false,
       permalink: '/docs/1.0.0/hello',
       source: path.join('@site', path.relative(siteDir, versionedDir), sourceB),
       title: 'hello',
@@ -318,6 +328,7 @@ describe('versioned site', () => {
     });
     expect(dataC).toEqual({
       id: 'version-1.0.1/foo/bar',
+      isDocsHomePage: false,
       permalink: '/docs/foo/bar',
       source: path.join('@site', path.relative(siteDir, versionedDir), sourceC),
       title: 'bar',
@@ -326,6 +337,7 @@ describe('versioned site', () => {
     });
     expect(dataD).toEqual({
       id: 'version-1.0.1/hello',
+      isDocsHomePage: false,
       permalink: '/docs/hello',
       source: path.join('@site', path.relative(siteDir, versionedDir), sourceD),
       title: 'hello',

From 32790d8287656cc3a5df2629f1ea93656e8fc66f Mon Sep 17 00:00:00 2001
From: slorber <lorber.sebastien@gmail.com>
Date: Mon, 8 Jun 2020 18:05:34 +0200
Subject: [PATCH 03/16] create special route for docs homepage + cleanup
 existing code

---
 .../__snapshots__/index.test.ts.snap          | 148 +++++++++++++++---
 .../src/index.ts                              |  58 ++-----
 .../src/types.ts                              |   2 -
 .../src/theme/DocPage/index.js                |  33 ++--
 .../src/theme/DocPage/index.js                |  42 ++---
 5 files changed, 167 insertions(+), 116 deletions(-)

diff --git a/packages/docusaurus-plugin-content-docs/src/__tests__/__snapshots__/index.test.ts.snap b/packages/docusaurus-plugin-content-docs/src/__tests__/__snapshots__/index.test.ts.snap
index c2df4e07d11c..a91e40b44079 100644
--- a/packages/docusaurus-plugin-content-docs/src/__tests__/__snapshots__/index.test.ts.snap
+++ b/packages/docusaurus-plugin-content-docs/src/__tests__/__snapshots__/index.test.ts.snap
@@ -59,10 +59,52 @@ Array [
     "component": "@theme/DocPage",
     "exact": true,
     "modules": Object {
-      "content": "@site/docs/hello.md",
-      "docsMetadata": "~docs/site-docs-hello-md-9df-base.json",
+      "docsMetadata": "~docs/docs-route-ff2.json",
     },
     "path": "/docs",
+    "priority": undefined,
+    "routes": Array [
+      Object {
+        "component": "@theme/DocItem",
+        "exact": true,
+        "modules": Object {
+          "content": "@site/docs/hello.md",
+        },
+        "path": "/docs/",
+      },
+      Object {
+        "component": "@theme/DocItem",
+        "exact": true,
+        "modules": Object {
+          "content": "@site/docs/foo/bar.md",
+        },
+        "path": "/docs/foo/bar",
+      },
+      Object {
+        "component": "@theme/DocItem",
+        "exact": true,
+        "modules": Object {
+          "content": "@site/docs/foo/baz.md",
+        },
+        "path": "/docs/foo/bazSlug.html",
+      },
+      Object {
+        "component": "@theme/DocItem",
+        "exact": true,
+        "modules": Object {
+          "content": "@site/docs/ipsum.md",
+        },
+        "path": "/docs/ipsum",
+      },
+      Object {
+        "component": "@theme/DocItem",
+        "exact": true,
+        "modules": Object {
+          "content": "@site/docs/lorem.md",
+        },
+        "path": "/docs/lorem",
+      },
+    ],
   },
   Object {
     "component": "@theme/DocPage",
@@ -133,28 +175,36 @@ Array [
     "component": "@theme/DocPage",
     "exact": true,
     "modules": Object {
-      "content": "@site/versioned_docs/version-1.0.1/hello.md",
-      "docsMetadata": "~docs/site-versioned-docs-version-1-0-1-hello-md-0c7-base.json",
-    },
-    "path": "/docs",
-  },
-  Object {
-    "component": "@theme/DocPage",
-    "exact": true,
-    "modules": Object {
-      "content": "@site/versioned_docs/version-1.0.0/hello.md",
-      "docsMetadata": "~docs/site-versioned-docs-version-1-0-0-hello-md-3ef-base.json",
+      "docsMetadata": "~docs/docs-1-0-0-route-660.json",
     },
     "path": "/docs/1.0.0",
-  },
-  Object {
-    "component": "@theme/DocPage",
-    "exact": true,
-    "modules": Object {
-      "content": "@site/docs/hello.md",
-      "docsMetadata": "~docs/site-docs-hello-md-9df-base.json",
-    },
-    "path": "/docs/next",
+    "priority": undefined,
+    "routes": Array [
+      Object {
+        "component": "@theme/DocItem",
+        "exact": true,
+        "modules": Object {
+          "content": "@site/versioned_docs/version-1.0.0/hello.md",
+        },
+        "path": "/docs/1.0.0/",
+      },
+      Object {
+        "component": "@theme/DocItem",
+        "exact": true,
+        "modules": Object {
+          "content": "@site/versioned_docs/version-1.0.0/foo/bar.md",
+        },
+        "path": "/docs/1.0.0/foo/barSlug",
+      },
+      Object {
+        "component": "@theme/DocItem",
+        "exact": true,
+        "modules": Object {
+          "content": "@site/versioned_docs/version-1.0.0/foo/baz.md",
+        },
+        "path": "/docs/1.0.0/foo/baz",
+      },
+    ],
   },
   Object {
     "component": "@theme/DocPage",
@@ -190,6 +240,33 @@ Array [
       },
     ],
   },
+  Object {
+    "component": "@theme/DocPage",
+    "exact": true,
+    "modules": Object {
+      "docsMetadata": "~docs/docs-next-route-1c8.json",
+    },
+    "path": "/docs/next",
+    "priority": undefined,
+    "routes": Array [
+      Object {
+        "component": "@theme/DocItem",
+        "exact": true,
+        "modules": Object {
+          "content": "@site/docs/hello.md",
+        },
+        "path": "/docs/next/",
+      },
+      Object {
+        "component": "@theme/DocItem",
+        "exact": true,
+        "modules": Object {
+          "content": "@site/docs/foo/bar.md",
+        },
+        "path": "/docs/next/foo/barSlug",
+      },
+    ],
+  },
   Object {
     "component": "@theme/DocPage",
     "modules": Object {
@@ -216,6 +293,33 @@ Array [
       },
     ],
   },
+  Object {
+    "component": "@theme/DocPage",
+    "exact": true,
+    "modules": Object {
+      "docsMetadata": "~docs/docs-route-ff2.json",
+    },
+    "path": "/docs",
+    "priority": -1,
+    "routes": Array [
+      Object {
+        "component": "@theme/DocItem",
+        "exact": true,
+        "modules": Object {
+          "content": "@site/versioned_docs/version-1.0.1/hello.md",
+        },
+        "path": "/docs/",
+      },
+      Object {
+        "component": "@theme/DocItem",
+        "exact": true,
+        "modules": Object {
+          "content": "@site/versioned_docs/version-1.0.1/foo/bar.md",
+        },
+        "path": "/docs/foo/bar",
+      },
+    ],
+  },
   Object {
     "component": "@theme/DocPage",
     "modules": Object {
diff --git a/packages/docusaurus-plugin-content-docs/src/index.ts b/packages/docusaurus-plugin-content-docs/src/index.ts
index c89e52e2efb2..ee93df368010 100644
--- a/packages/docusaurus-plugin-content-docs/src/index.ts
+++ b/packages/docusaurus-plugin-content-docs/src/index.ts
@@ -345,42 +345,6 @@ Available document ids=
       ): Promise<RouteConfig[]> => {
         const routes = await Promise.all(
           metadataItems.map(async (metadataItem) => {
-            if (metadataItem.isDocsHomePage) {
-              const versionDocsPathPrefix =
-                (metadataItem?.version === versioning.latestVersion
-                  ? ''
-                  : metadataItem.version!) ?? '';
-
-              const docsBaseMetadata = createDocsBaseMetadata(
-                metadataItem.version!,
-              );
-              docsBaseMetadata.isHomePage = true;
-              docsBaseMetadata.homePagePath = normalizeUrl([
-                baseUrl,
-                homePageDocsRoutePath,
-                versionDocsPathPrefix,
-              ]);
-              const docsBaseMetadataPath = await createData(
-                `${docuHash(metadataItem.source)}-base.json`,
-                JSON.stringify(docsBaseMetadata, null, 2),
-              );
-
-              // Add a route for docs home page.
-              addRoute({
-                path: normalizeUrl([
-                  baseUrl,
-                  homePageDocsRoutePath,
-                  versionDocsPathPrefix,
-                ]),
-                component: docLayoutComponent,
-                exact: true,
-                modules: {
-                  docsMetadata: aliasedSource(docsBaseMetadataPath),
-                  content: metadataItem.source,
-                },
-              });
-            }
-
             await createData(
               // Note that this created data path must be in sync with
               // metadataPath provided to mdx-loader.
@@ -410,13 +374,27 @@ Available document ids=
         routes: RouteConfig[],
         priority?: number,
       ) => {
+        const docsParentRoute = normalizeUrl([docsBaseRoute, ':route']);
+
         const docsBaseMetadataPath = await createData(
-          `${docuHash(docsBaseRoute)}.json`,
+          `${docuHash(docsParentRoute)}.json`,
           JSON.stringify(docsBaseMetadata, null, 2),
         );
 
+        // Route for /docs
         addRoute({
           path: docsBaseRoute,
+          exact: true,
+          component: docLayoutComponent,
+          routes,
+          modules: {
+            docsMetadata: aliasedSource(docsBaseMetadataPath),
+          },
+          priority,
+        });
+        // Route for /docs/:route
+        addRoute({
+          path: docsParentRoute,
           component: docLayoutComponent,
           routes,
           modules: {
@@ -440,12 +418,11 @@ Available document ids=
             );
 
             const isLatestVersion = version === versioning.latestVersion;
-            const docsBasePermalink = normalizeUrl([
+            const docsBaseRoute = normalizeUrl([
               baseUrl,
               routeBasePath,
               isLatestVersion ? '' : version,
             ]);
-            const docsBaseRoute = normalizeUrl([docsBasePermalink, ':route']);
             const docsBaseMetadata = createDocsBaseMetadata(version);
 
             // We want latest version route config to be placed last in the
@@ -462,8 +439,7 @@ Available document ids=
       } else {
         const routes = await genRoutes(Object.values(content.docsMetadata));
         const docsBaseMetadata = createDocsBaseMetadata();
-
-        const docsBaseRoute = normalizeUrl([baseUrl, routeBasePath, ':route']);
+        const docsBaseRoute = normalizeUrl([baseUrl, routeBasePath]);
         return addBaseRoute(docsBaseRoute, docsBaseMetadata, routes);
       }
     },
diff --git a/packages/docusaurus-plugin-content-docs/src/types.ts b/packages/docusaurus-plugin-content-docs/src/types.ts
index ae535d5b358f..3654e685a8a6 100644
--- a/packages/docusaurus-plugin-content-docs/src/types.ts
+++ b/packages/docusaurus-plugin-content-docs/src/types.ts
@@ -165,8 +165,6 @@ export type DocsBaseMetadata = Pick<
   'docsSidebars' | 'permalinkToSidebar'
 > & {
   version?: string;
-  isHomePage?: boolean;
-  homePagePath?: string;
 };
 
 export type VersioningEnv = {
diff --git a/packages/docusaurus-theme-bootstrap/src/theme/DocPage/index.js b/packages/docusaurus-theme-bootstrap/src/theme/DocPage/index.js
index 93f92e5fc4a3..78c691a07cc6 100644
--- a/packages/docusaurus-theme-bootstrap/src/theme/DocPage/index.js
+++ b/packages/docusaurus-theme-bootstrap/src/theme/DocPage/index.js
@@ -8,7 +8,6 @@
 import React from 'react';
 import renderRoutes from '@docusaurus/renderRoutes';
 import NotFound from '@theme/NotFound';
-import DocItem from '@theme/DocItem';
 import DocSidebar from '@theme/DocSidebar';
 import MDXComponents from '@theme/MDXComponents';
 import Layout from '@theme/Layout';
@@ -16,24 +15,16 @@ import {MDXProvider} from '@mdx-js/react';
 import {matchPath} from '@docusaurus/router';
 
 function DocPage(props) {
-  const {route: baseRoute, docsMetadata, location, content} = props;
-  const {
-    permalinkToSidebar,
-    docsSidebars,
-    isHomePage,
-    homePagePath,
-  } = docsMetadata;
+  const {route: baseRoute, docsMetadata, location} = props;
   // case-sensitive route such as it is defined in the sidebar
-  const currentRoute = !isHomePage
-    ? baseRoute.routes.find((route) => {
-        return matchPath(location.pathname, route);
-      }) || {}
-    : {};
-  const sidebar = isHomePage
-    ? content.metadata.sidebar
-    : permalinkToSidebar[currentRoute.path];
+  const currentRoute =
+    baseRoute.routes.find((route) => {
+      return matchPath(location.pathname, route);
+    }) || {};
+  const {permalinkToSidebar, docsSidebars} = docsMetadata;
+  const sidebar = permalinkToSidebar[currentRoute.path];
 
-  if (!isHomePage && Object.keys(currentRoute).length === 0) {
+  if (Object.keys(currentRoute).length === 0) {
     return <NotFound {...props} />;
   }
 
@@ -41,16 +32,12 @@ function DocPage(props) {
     <Layout title="Doc page" description="My Doc page">
       <DocSidebar
         docsSidebars={docsSidebars}
-        path={isHomePage ? homePagePath : currentRoute.path}
+        path={currentRoute.path}
         sidebar={sidebar}
       />
       <section className="offset-1 mr-4 mt-4 col-xl-6 offset-xl-4 p-0 justify-content-center align-self-center overflow-hidden">
         <MDXProvider components={MDXComponents}>
-          {isHomePage ? (
-            <DocItem content={content} />
-          ) : (
-            renderRoutes(baseRoute.routes)
-          )}
+          {renderRoutes(baseRoute.routes)}
         </MDXProvider>
       </section>
     </Layout>
diff --git a/packages/docusaurus-theme-classic/src/theme/DocPage/index.js b/packages/docusaurus-theme-classic/src/theme/DocPage/index.js
index 397fecd22784..adee2291b84c 100644
--- a/packages/docusaurus-theme-classic/src/theme/DocPage/index.js
+++ b/packages/docusaurus-theme-classic/src/theme/DocPage/index.js
@@ -11,7 +11,6 @@ import {MDXProvider} from '@mdx-js/react';
 import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
 import renderRoutes from '@docusaurus/renderRoutes';
 import Layout from '@theme/Layout';
-import DocItem from '@theme/DocItem';
 import DocSidebar from '@theme/DocSidebar';
 import MDXComponents from '@theme/MDXComponents';
 import NotFound from '@theme/NotFound';
@@ -20,31 +19,22 @@ import {matchPath} from '@docusaurus/router';
 import styles from './styles.module.css';
 
 function DocPage(props) {
-  const {route: baseRoute, docsMetadata, location, content} = props;
+  const {route: baseRoute, docsMetadata, location} = props;
+  // case-sensitive route such as it is defined in the sidebar
+  const currentRoute =
+    baseRoute.routes.find((route) => {
+      return matchPath(location.pathname, route);
+    }) || {};
+  const {permalinkToSidebar, docsSidebars, version} = docsMetadata;
+  const sidebar = permalinkToSidebar[currentRoute.path];
   const {
-    permalinkToSidebar,
-    docsSidebars,
-    version,
-    isHomePage,
-    homePagePath,
-  } = docsMetadata;
-
-  // Get case-sensitive route such as it is defined in the sidebar.
-  const currentRoute = !isHomePage
-    ? baseRoute.routes.find((route) => {
-        return matchPath(location.pathname, route);
-      }) || {}
-    : {};
-
-  const sidebar = isHomePage
-    ? content.metadata.sidebar
-    : permalinkToSidebar[currentRoute.path];
-  const {
-    siteConfig: {themeConfig: {sidebarCollapsible = true} = {}} = {},
+    siteConfig: {themeConfig = {}} = {},
     isClient,
   } = useDocusaurusContext();
 
-  if (!isHomePage && Object.keys(currentRoute).length === 0) {
+  const {sidebarCollapsible = true} = themeConfig;
+
+  if (Object.keys(currentRoute).length === 0) {
     return <NotFound {...props} />;
   }
 
@@ -55,7 +45,7 @@ function DocPage(props) {
           <div className={styles.docSidebarContainer} role="complementary">
             <DocSidebar
               docsSidebars={docsSidebars}
-              path={isHomePage ? homePagePath : currentRoute.path}
+              path={currentRoute.path}
               sidebar={sidebar}
               sidebarCollapsible={sidebarCollapsible}
             />
@@ -63,11 +53,7 @@ function DocPage(props) {
         )}
         <main className={styles.docMainContainer}>
           <MDXProvider components={MDXComponents}>
-            {isHomePage ? (
-              <DocItem content={content} />
-            ) : (
-              renderRoutes(baseRoute.routes)
-            )}
+            {renderRoutes(baseRoute.routes)}
           </MDXProvider>
         </main>
       </div>

From edd5a1d88339ba57f41071e4a638857b93bf58f9 Mon Sep 17 00:00:00 2001
From: slorber <lorber.sebastien@gmail.com>
Date: Mon, 8 Jun 2020 18:15:15 +0200
Subject: [PATCH 04/16] no need to create multiple docs parent paths

---
 .../__snapshots__/index.test.ts.snap          | 144 +-----------------
 .../src/index.ts                              |  12 +-
 .../src/metadata.ts                           |   2 +-
 3 files changed, 6 insertions(+), 152 deletions(-)

diff --git a/packages/docusaurus-plugin-content-docs/src/__tests__/__snapshots__/index.test.ts.snap b/packages/docusaurus-plugin-content-docs/src/__tests__/__snapshots__/index.test.ts.snap
index a91e40b44079..fc4d63152ec7 100644
--- a/packages/docusaurus-plugin-content-docs/src/__tests__/__snapshots__/index.test.ts.snap
+++ b/packages/docusaurus-plugin-content-docs/src/__tests__/__snapshots__/index.test.ts.snap
@@ -57,7 +57,7 @@ exports[`simple website content 2`] = `
 Array [
   Object {
     "component": "@theme/DocPage",
-    "exact": true,
+    "exact": false,
     "modules": Object {
       "docsMetadata": "~docs/docs-route-ff2.json",
     },
@@ -106,56 +106,6 @@ Array [
       },
     ],
   },
-  Object {
-    "component": "@theme/DocPage",
-    "modules": Object {
-      "docsMetadata": "~docs/docs-route-ff2.json",
-    },
-    "path": "/docs/:route",
-    "priority": undefined,
-    "routes": Array [
-      Object {
-        "component": "@theme/DocItem",
-        "exact": true,
-        "modules": Object {
-          "content": "@site/docs/hello.md",
-        },
-        "path": "/docs/",
-      },
-      Object {
-        "component": "@theme/DocItem",
-        "exact": true,
-        "modules": Object {
-          "content": "@site/docs/foo/bar.md",
-        },
-        "path": "/docs/foo/bar",
-      },
-      Object {
-        "component": "@theme/DocItem",
-        "exact": true,
-        "modules": Object {
-          "content": "@site/docs/foo/baz.md",
-        },
-        "path": "/docs/foo/bazSlug.html",
-      },
-      Object {
-        "component": "@theme/DocItem",
-        "exact": true,
-        "modules": Object {
-          "content": "@site/docs/ipsum.md",
-        },
-        "path": "/docs/ipsum",
-      },
-      Object {
-        "component": "@theme/DocItem",
-        "exact": true,
-        "modules": Object {
-          "content": "@site/docs/lorem.md",
-        },
-        "path": "/docs/lorem",
-      },
-    ],
-  },
 ]
 `;
 
@@ -173,7 +123,7 @@ exports[`versioned website content 1`] = `
 Array [
   Object {
     "component": "@theme/DocPage",
-    "exact": true,
+    "exact": false,
     "modules": Object {
       "docsMetadata": "~docs/docs-1-0-0-route-660.json",
     },
@@ -208,41 +158,7 @@ Array [
   },
   Object {
     "component": "@theme/DocPage",
-    "modules": Object {
-      "docsMetadata": "~docs/docs-1-0-0-route-660.json",
-    },
-    "path": "/docs/1.0.0/:route",
-    "priority": undefined,
-    "routes": Array [
-      Object {
-        "component": "@theme/DocItem",
-        "exact": true,
-        "modules": Object {
-          "content": "@site/versioned_docs/version-1.0.0/hello.md",
-        },
-        "path": "/docs/1.0.0/",
-      },
-      Object {
-        "component": "@theme/DocItem",
-        "exact": true,
-        "modules": Object {
-          "content": "@site/versioned_docs/version-1.0.0/foo/bar.md",
-        },
-        "path": "/docs/1.0.0/foo/barSlug",
-      },
-      Object {
-        "component": "@theme/DocItem",
-        "exact": true,
-        "modules": Object {
-          "content": "@site/versioned_docs/version-1.0.0/foo/baz.md",
-        },
-        "path": "/docs/1.0.0/foo/baz",
-      },
-    ],
-  },
-  Object {
-    "component": "@theme/DocPage",
-    "exact": true,
+    "exact": false,
     "modules": Object {
       "docsMetadata": "~docs/docs-next-route-1c8.json",
     },
@@ -269,33 +185,7 @@ Array [
   },
   Object {
     "component": "@theme/DocPage",
-    "modules": Object {
-      "docsMetadata": "~docs/docs-next-route-1c8.json",
-    },
-    "path": "/docs/next/:route",
-    "priority": undefined,
-    "routes": Array [
-      Object {
-        "component": "@theme/DocItem",
-        "exact": true,
-        "modules": Object {
-          "content": "@site/docs/hello.md",
-        },
-        "path": "/docs/next/",
-      },
-      Object {
-        "component": "@theme/DocItem",
-        "exact": true,
-        "modules": Object {
-          "content": "@site/docs/foo/bar.md",
-        },
-        "path": "/docs/next/foo/barSlug",
-      },
-    ],
-  },
-  Object {
-    "component": "@theme/DocPage",
-    "exact": true,
+    "exact": false,
     "modules": Object {
       "docsMetadata": "~docs/docs-route-ff2.json",
     },
@@ -320,32 +210,6 @@ Array [
       },
     ],
   },
-  Object {
-    "component": "@theme/DocPage",
-    "modules": Object {
-      "docsMetadata": "~docs/docs-route-ff2.json",
-    },
-    "path": "/docs/:route",
-    "priority": -1,
-    "routes": Array [
-      Object {
-        "component": "@theme/DocItem",
-        "exact": true,
-        "modules": Object {
-          "content": "@site/versioned_docs/version-1.0.1/hello.md",
-        },
-        "path": "/docs/",
-      },
-      Object {
-        "component": "@theme/DocItem",
-        "exact": true,
-        "modules": Object {
-          "content": "@site/versioned_docs/version-1.0.1/foo/bar.md",
-        },
-        "path": "/docs/foo/bar",
-      },
-    ],
-  },
 ]
 `;
 
diff --git a/packages/docusaurus-plugin-content-docs/src/index.ts b/packages/docusaurus-plugin-content-docs/src/index.ts
index ee93df368010..4fb22c1f8740 100644
--- a/packages/docusaurus-plugin-content-docs/src/index.ts
+++ b/packages/docusaurus-plugin-content-docs/src/index.ts
@@ -384,17 +384,7 @@ Available document ids=
         // Route for /docs
         addRoute({
           path: docsBaseRoute,
-          exact: true,
-          component: docLayoutComponent,
-          routes,
-          modules: {
-            docsMetadata: aliasedSource(docsBaseMetadataPath),
-          },
-          priority,
-        });
-        // Route for /docs/:route
-        addRoute({
-          path: docsParentRoute,
+          exact: false,
           component: docLayoutComponent,
           routes,
           modules: {
diff --git a/packages/docusaurus-plugin-content-docs/src/metadata.ts b/packages/docusaurus-plugin-content-docs/src/metadata.ts
index 9033cc516fa2..8fa61d9a0028 100644
--- a/packages/docusaurus-plugin-content-docs/src/metadata.ts
+++ b/packages/docusaurus-plugin-content-docs/src/metadata.ts
@@ -127,7 +127,7 @@ export default async function processMetadata({
   let routePath;
   if (isDocsHomePage) {
     // TODO can we remove this trailing / ?
-    // Seems it's not that easy...
+    // Seems it's not that easy... the sidebar disappears on homepage xD
     routePath = '/';
   } else {
     routePath =

From 280f08f555141a011b6162022f15ba9c972c6e26 Mon Sep 17 00:00:00 2001
From: slorber <lorber.sebastien@gmail.com>
Date: Mon, 8 Jun 2020 18:16:04 +0200
Subject: [PATCH 05/16] useful comment

---
 packages/docusaurus-plugin-content-docs/src/index.ts | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/packages/docusaurus-plugin-content-docs/src/index.ts b/packages/docusaurus-plugin-content-docs/src/index.ts
index 4fb22c1f8740..ca45f22609e3 100644
--- a/packages/docusaurus-plugin-content-docs/src/index.ts
+++ b/packages/docusaurus-plugin-content-docs/src/index.ts
@@ -381,7 +381,8 @@ Available document ids=
           JSON.stringify(docsBaseMetadata, null, 2),
         );
 
-        // Route for /docs
+        // Parent route for /docs
+        // should allow matching /docs/* as well (exact=false)
         addRoute({
           path: docsBaseRoute,
           exact: false,

From 8e91f2b8ec1e2952e22a3105fa31f29bc72af1ed Mon Sep 17 00:00:00 2001
From: slorber <lorber.sebastien@gmail.com>
Date: Mon, 8 Jun 2020 18:54:07 +0200
Subject: [PATCH 06/16] add test for slug + doc home usage at the same time
 error

---
 .../docs/docWithSlug.md                       |  5 +++++
 .../src/__tests__/metadata.test.ts            | 20 +++++++++++++++++++
 .../src/types.ts                              |  2 +-
 3 files changed, 26 insertions(+), 1 deletion(-)
 create mode 100644 packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/bad-slug-on-doc-home-site/docs/docWithSlug.md

diff --git a/packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/bad-slug-on-doc-home-site/docs/docWithSlug.md b/packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/bad-slug-on-doc-home-site/docs/docWithSlug.md
new file mode 100644
index 000000000000..a3fa2f34fc9a
--- /dev/null
+++ b/packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/bad-slug-on-doc-home-site/docs/docWithSlug.md
@@ -0,0 +1,5 @@
+---
+slug: docWithSlug.html
+---
+
+Lorem
diff --git a/packages/docusaurus-plugin-content-docs/src/__tests__/metadata.test.ts b/packages/docusaurus-plugin-content-docs/src/__tests__/metadata.test.ts
index 2b50045d6c67..0bb9ae6e6316 100644
--- a/packages/docusaurus-plugin-content-docs/src/__tests__/metadata.test.ts
+++ b/packages/docusaurus-plugin-content-docs/src/__tests__/metadata.test.ts
@@ -214,6 +214,26 @@ describe('simple site', () => {
       ),
     );
   });
+
+  test('docs with slug on doc home', async () => {
+    const badSiteDir = path.join(fixtureDir, 'bad-slug-on-doc-home-site');
+    const options = {
+      routeBasePath,
+      homePageId: 'docWithSlug',
+    };
+
+    await expect(
+      processMetadata({
+        source: 'docWithSlug.md',
+        refDir: path.join(badSiteDir, 'docs'),
+        context,
+        options,
+        env,
+      }),
+    ).rejects.toThrowErrorMatchingInlineSnapshot(
+      `"The docs homepage (homePageId=docWithSlug) is not allowed to have a frontmatter slug=docWithSlug.html => you have to chooser either homePageId or slug, not both"`,
+    );
+  });
 });
 
 describe('versioned site', () => {
diff --git a/packages/docusaurus-plugin-content-docs/src/types.ts b/packages/docusaurus-plugin-content-docs/src/types.ts
index 3654e685a8a6..82f99cc3f932 100644
--- a/packages/docusaurus-plugin-content-docs/src/types.ts
+++ b/packages/docusaurus-plugin-content-docs/src/types.ts
@@ -7,7 +7,7 @@
 
 export interface MetadataOptions {
   routeBasePath: string;
-  homePageId: string;
+  homePageId?: string;
   editUrl?: string;
   showLastUpdateTime?: boolean;
   showLastUpdateAuthor?: boolean;

From 3537cb80b756a353cef4907485d407b7685ec823 Mon Sep 17 00:00:00 2001
From: slorber <lorber.sebastien@gmail.com>
Date: Mon, 8 Jun 2020 19:11:17 +0200
Subject: [PATCH 07/16] remove confusing variable name

---
 packages/docusaurus-plugin-content-docs/src/index.ts | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/packages/docusaurus-plugin-content-docs/src/index.ts b/packages/docusaurus-plugin-content-docs/src/index.ts
index ca45f22609e3..459b1215573f 100644
--- a/packages/docusaurus-plugin-content-docs/src/index.ts
+++ b/packages/docusaurus-plugin-content-docs/src/index.ts
@@ -374,10 +374,8 @@ Available document ids=
         routes: RouteConfig[],
         priority?: number,
       ) => {
-        const docsParentRoute = normalizeUrl([docsBaseRoute, ':route']);
-
         const docsBaseMetadataPath = await createData(
-          `${docuHash(docsParentRoute)}.json`,
+          `${docuHash(normalizeUrl([docsBaseRoute, 'route']))}.json`,
           JSON.stringify(docsBaseMetadata, null, 2),
         );
 

From ba27841479177badd43b5dae1976943768769abb Mon Sep 17 00:00:00 2001
From: slorber <lorber.sebastien@gmail.com>
Date: Mon, 8 Jun 2020 19:21:33 +0200
Subject: [PATCH 08/16] fix tests by using same suffix as before for docs base
 metadata path

---
 packages/docusaurus-plugin-content-docs/src/index.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/docusaurus-plugin-content-docs/src/index.ts b/packages/docusaurus-plugin-content-docs/src/index.ts
index 459b1215573f..1833522caf34 100644
--- a/packages/docusaurus-plugin-content-docs/src/index.ts
+++ b/packages/docusaurus-plugin-content-docs/src/index.ts
@@ -375,7 +375,7 @@ Available document ids=
         priority?: number,
       ) => {
         const docsBaseMetadataPath = await createData(
-          `${docuHash(normalizeUrl([docsBaseRoute, 'route']))}.json`,
+          `${docuHash(normalizeUrl([docsBaseRoute, ':route']))}.json`,
           JSON.stringify(docsBaseMetadata, null, 2),
         );
 

From 5e7ee40373740c451f9d34cf3645e882fa24affa Mon Sep 17 00:00:00 2001
From: slorber <lorber.sebastien@gmail.com>
Date: Tue, 9 Jun 2020 17:39:27 +0200
Subject: [PATCH 09/16] metadata: use homePageId correctly for nested docs: the
 full docId (including /) should be used to compare against homePageId

---
 .../src/__tests__/metadata.test.ts            | 50 +++++++++++++++++++
 .../src/metadata.ts                           |  7 +--
 2 files changed, 52 insertions(+), 5 deletions(-)

diff --git a/packages/docusaurus-plugin-content-docs/src/__tests__/metadata.test.ts b/packages/docusaurus-plugin-content-docs/src/__tests__/metadata.test.ts
index 5cfe94f0dc29..e020203b8cdc 100644
--- a/packages/docusaurus-plugin-content-docs/src/__tests__/metadata.test.ts
+++ b/packages/docusaurus-plugin-content-docs/src/__tests__/metadata.test.ts
@@ -62,6 +62,56 @@ describe('simple site', () => {
     });
   });
 
+  test('homePageId doc', async () => {
+    const source = path.join('hello.md');
+    const options = {
+      routeBasePath,
+      homePageId: 'hello',
+    };
+
+    const data = await processMetadata({
+      source,
+      refDir: docsDir,
+      context,
+      options,
+      env,
+    });
+
+    expect(data).toEqual({
+      id: 'hello',
+      isDocsHomePage: true,
+      permalink: '/docs/',
+      source: path.join('@site', routeBasePath, source),
+      title: 'Hello, World !',
+      description: `Hi, Endilie here :)`,
+    });
+  });
+
+  test('homePageId doc nested', async () => {
+    const source = path.join('foo', 'bar.md');
+    const options = {
+      routeBasePath,
+      homePageId: 'foo/bar',
+    };
+
+    const data = await processMetadata({
+      source,
+      refDir: docsDir,
+      context,
+      options,
+      env,
+    });
+
+    expect(data).toEqual({
+      id: 'foo/bar',
+      isDocsHomePage: true,
+      permalink: '/docs/',
+      source: path.join('@site', routeBasePath, source),
+      title: 'Bar',
+      description: 'This is custom description',
+    });
+  });
+
   test('docs with editUrl', async () => {
     const editUrl =
       'https://github.com/facebook/docusaurus/edit/master/website';
diff --git a/packages/docusaurus-plugin-content-docs/src/metadata.ts b/packages/docusaurus-plugin-content-docs/src/metadata.ts
index 8fa61d9a0028..43fba1a958be 100644
--- a/packages/docusaurus-plugin-content-docs/src/metadata.ts
+++ b/packages/docusaurus-plugin-content-docs/src/metadata.ts
@@ -100,9 +100,9 @@ export default async function processMetadata({
   if (baseID.includes('/')) {
     throw new Error('Document id cannot include "/".');
   }
+  const id = dirName !== '.' ? `${dirName}/${baseID}` : baseID;
 
-  const isDocsHomePage = homePageId === baseID;
-
+  const isDocsHomePage = homePageId === id;
   if (frontMatter.slug && isDocsHomePage) {
     throw new Error(
       `The docs homepage (homePageId=${homePageId}) is not allowed to have a frontmatter slug=${frontMatter.slug} => you have to chooser either homePageId or slug, not both`,
@@ -113,9 +113,6 @@ export default async function processMetadata({
   if (baseSlug.includes('/')) {
     throw new Error('Document slug cannot include "/".');
   }
-
-  // Append subdirectory as part of id/slug.
-  const id = dirName !== '.' ? `${dirName}/${baseID}` : baseID;
   const slug = dirName !== '.' ? `${dirName}/${baseSlug}` : baseSlug;
 
   // Default title is the id.

From e996ad29b7b2c3838445856693de16ab9b4f9535 Mon Sep 17 00:00:00 2001
From: slorber <lorber.sebastien@gmail.com>
Date: Tue, 9 Jun 2020 17:46:05 +0200
Subject: [PATCH 10/16] add folder/testNested test doc

---
 website/docs/folder/testNested.md | 6 ++++++
 website/docusaurus.config.js      | 3 ++-
 website/sidebars.js               | 7 ++++++-
 3 files changed, 14 insertions(+), 2 deletions(-)
 create mode 100644 website/docs/folder/testNested.md

diff --git a/website/docs/folder/testNested.md b/website/docs/folder/testNested.md
new file mode 100644
index 000000000000..cee71f53dfab
--- /dev/null
+++ b/website/docs/folder/testNested.md
@@ -0,0 +1,6 @@
+---
+id: testNested
+title: TEST NESTED
+---
+
+TEST NESTED DOC CONTENT
diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js
index 25781444366f..352b29a466f3 100644
--- a/website/docusaurus.config.js
+++ b/website/docusaurus.config.js
@@ -36,7 +36,8 @@ module.exports = {
       '@docusaurus/preset-classic',
       {
         docs: {
-          homePageId: 'introduction',
+          // homePageId: 'introduction',
+          homePageId: 'folder/testNested',
           path: 'docs',
           sidebarPath: require.resolve('./sidebars.js'),
           editUrl:
diff --git a/website/sidebars.js b/website/sidebars.js
index 94f27479d461..65551bde1e45 100644
--- a/website/sidebars.js
+++ b/website/sidebars.js
@@ -26,7 +26,12 @@ module.exports = {
         'styling-layout',
         'static-assets',
         {
-          Docs: ['docs-introduction', 'markdown-features', 'versioning'],
+          Docs: [
+            'folder/testNested',
+            'docs-introduction',
+            'markdown-features',
+            'versioning',
+          ],
         },
         'blog',
         'search',

From 66cd083522c7aeab3be9250297a1327c754a3da3 Mon Sep 17 00:00:00 2001
From: slorber <lorber.sebastien@gmail.com>
Date: Tue, 9 Jun 2020 19:01:57 +0200
Subject: [PATCH 11/16] refactor a bit processMetadata, the home should be
 handled correctly for all versions

---
 .../src/metadata.ts                           | 60 +++++++++++++------
 1 file changed, 41 insertions(+), 19 deletions(-)

diff --git a/packages/docusaurus-plugin-content-docs/src/metadata.ts b/packages/docusaurus-plugin-content-docs/src/metadata.ts
index 43fba1a958be..a86d028954fa 100644
--- a/packages/docusaurus-plugin-content-docs/src/metadata.ts
+++ b/packages/docusaurus-plugin-content-docs/src/metadata.ts
@@ -15,7 +15,43 @@ import {
 import {LoadContext} from '@docusaurus/types';
 
 import lastUpdate from './lastUpdate';
-import {MetadataRaw, LastUpdateData, MetadataOptions, Env} from './types';
+import {
+  MetadataRaw,
+  LastUpdateData,
+  MetadataOptions,
+  Env,
+  VersioningEnv,
+} from './types';
+
+function removeVersionPrefix(str: string, version: string): string {
+  return str.replace(new RegExp(`^version-${version}/`), '');
+}
+
+function inferVersion(
+  dirName: string,
+  versioning: VersioningEnv,
+): string | undefined {
+  if (!versioning.enabled) {
+    return undefined;
+  }
+  if (/^version-/.test(dirName)) {
+    const inferredVersion = dirName
+      .split('/', 1)
+      .shift()!
+      .replace(/^version-/, '');
+    if (inferredVersion && versioning.versions.includes(inferredVersion)) {
+      return inferredVersion;
+    } else {
+      throw new Error(
+        `Can't infer version from folder=${dirName}
+Expected versions:
+- ${versioning.versions.join('- ')}`,
+      );
+    }
+  } else {
+    return 'next';
+  }
+}
 
 type Args = {
   source: string;
@@ -67,21 +103,8 @@ export default async function processMetadata({
   const fileMarkdownPromise = parseMarkdownFile(filePath);
   const lastUpdatedPromise = lastUpdated(filePath, options);
 
-  let version;
   const dirName = path.dirname(source);
-  if (versioning.enabled) {
-    if (/^version-/.test(dirName)) {
-      const inferredVersion = dirName
-        .split('/', 1)
-        .shift()!
-        .replace(/^version-/, '');
-      if (inferredVersion && versioning.versions.includes(inferredVersion)) {
-        version = inferredVersion;
-      }
-    } else {
-      version = 'next';
-    }
-  }
+  const version = inferVersion(dirName, versioning);
 
   // The version portion of the url path. Eg: 'next', '1.0.0', and ''.
   const versionPath =
@@ -101,8 +124,9 @@ export default async function processMetadata({
     throw new Error('Document id cannot include "/".');
   }
   const id = dirName !== '.' ? `${dirName}/${baseID}` : baseID;
+  const idWithoutVersion = version ? removeVersionPrefix(id, version) : id;
 
-  const isDocsHomePage = homePageId === id;
+  const isDocsHomePage = idWithoutVersion === homePageId;
   if (frontMatter.slug && isDocsHomePage) {
     throw new Error(
       `The docs homepage (homePageId=${homePageId}) is not allowed to have a frontmatter slug=${frontMatter.slug} => you have to chooser either homePageId or slug, not both`,
@@ -128,9 +152,7 @@ export default async function processMetadata({
     routePath = '/';
   } else {
     routePath =
-      version && version !== 'next'
-        ? slug.replace(new RegExp(`^version-${version}/`), '')
-        : slug;
+      version && version !== 'next' ? removeVersionPrefix(slug, version) : slug;
   }
 
   const permalink = normalizeUrl([

From fd94d288b600e7d0abe916c0ddf137a6ce9f8b5f Mon Sep 17 00:00:00 2001
From: slorber <lorber.sebastien@gmail.com>
Date: Wed, 10 Jun 2020 16:21:31 +0200
Subject: [PATCH 12/16] Workaround to fix issue when parent layout route
 (DocPage) has same path as the child route (DocItem): see
 https://github.com/facebook/docusaurus/issues/2917

---
 .../src/index.ts                              | 24 ++++++++++++-------
 1 file changed, 15 insertions(+), 9 deletions(-)

diff --git a/packages/docusaurus-plugin-content-docs/src/index.ts b/packages/docusaurus-plugin-content-docs/src/index.ts
index 1833522caf34..81d56718b4bf 100644
--- a/packages/docusaurus-plugin-content-docs/src/index.ts
+++ b/packages/docusaurus-plugin-content-docs/src/index.ts
@@ -368,6 +368,9 @@ Available document ids=
         );
       };
 
+      // This is the base route of the document root (for a doc given version)
+      // (/docs, /docs/next, /docs/1.0 etc...)
+      // The component applies the layout and renders the appropriate doc
       const addBaseRoute = async (
         docsBaseRoute: string,
         docsBaseMetadata: DocsBaseMetadata,
@@ -379,13 +382,16 @@ Available document ids=
           JSON.stringify(docsBaseMetadata, null, 2),
         );
 
-        // Parent route for /docs
-        // should allow matching /docs/* as well (exact=false)
+        // Important: the layout component should not end with /,
+        // as it conflicts with the home doc
+        // Workaround fix for https://github.com/facebook/docusaurus/issues/2917
+        const path = docsBaseRoute === '/' ? '' : docsBaseRoute;
+
         addRoute({
-          path: docsBaseRoute,
-          exact: false,
-          component: docLayoutComponent,
-          routes,
+          path,
+          exact: false, // allow matching /docs/* as well
+          component: docLayoutComponent, // main docs component (DocPage)
+          routes, // subroute for each doc
           modules: {
             docsMetadata: aliasedSource(docsBaseMetadataPath),
           },
@@ -414,13 +420,13 @@ Available document ids=
             ]);
             const docsBaseMetadata = createDocsBaseMetadata(version);
 
-            // We want latest version route config to be placed last in the
-            // generated routeconfig. Otherwise, `/docs/next/foo` will match
-            // `/docs/:route` instead of `/docs/next/:route`.
             return addBaseRoute(
               docsBaseRoute,
               docsBaseMetadata,
               routes,
+              // We want latest version route config to be placed last in the
+              // generated routeconfig. Otherwise, `/docs/next/foo` will match
+              // `/docs/:route` instead of `/docs/next/:route`.
               isLatestVersion ? -1 : undefined,
             );
           }),

From 268f9641ed7395266ffb3a7784f4a1e504b196cd Mon Sep 17 00:00:00 2001
From: slorber <lorber.sebastien@gmail.com>
Date: Wed, 10 Jun 2020 16:22:56 +0200
Subject: [PATCH 13/16] revert homePageId

---
 website/docusaurus.config.js | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js
index 352b29a466f3..25781444366f 100644
--- a/website/docusaurus.config.js
+++ b/website/docusaurus.config.js
@@ -36,8 +36,7 @@ module.exports = {
       '@docusaurus/preset-classic',
       {
         docs: {
-          // homePageId: 'introduction',
-          homePageId: 'folder/testNested',
+          homePageId: 'introduction',
           path: 'docs',
           sidebarPath: require.resolve('./sidebars.js'),
           editUrl:

From 0c0b6d111ebc52dbe45d8a5d244be8da758275ed Mon Sep 17 00:00:00 2001
From: slorber <lorber.sebastien@gmail.com>
Date: Wed, 10 Jun 2020 16:23:23 +0200
Subject: [PATCH 14/16] remove test doc

---
 website/docs/folder/testNested.md | 6 ------
 1 file changed, 6 deletions(-)
 delete mode 100644 website/docs/folder/testNested.md

diff --git a/website/docs/folder/testNested.md b/website/docs/folder/testNested.md
deleted file mode 100644
index cee71f53dfab..000000000000
--- a/website/docs/folder/testNested.md
+++ /dev/null
@@ -1,6 +0,0 @@
----
-id: testNested
-title: TEST NESTED
----
-
-TEST NESTED DOC CONTENT

From 74d84d9bc36abe360337864983558a59e4df9b2a Mon Sep 17 00:00:00 2001
From: slorber <lorber.sebastien@gmail.com>
Date: Wed, 10 Jun 2020 16:30:00 +0200
Subject: [PATCH 15/16] remove test doc

---
 website/sidebars.js | 7 +------
 1 file changed, 1 insertion(+), 6 deletions(-)

diff --git a/website/sidebars.js b/website/sidebars.js
index 65551bde1e45..94f27479d461 100644
--- a/website/sidebars.js
+++ b/website/sidebars.js
@@ -26,12 +26,7 @@ module.exports = {
         'styling-layout',
         'static-assets',
         {
-          Docs: [
-            'folder/testNested',
-            'docs-introduction',
-            'markdown-features',
-            'versioning',
-          ],
+          Docs: ['docs-introduction', 'markdown-features', 'versioning'],
         },
         'blog',
         'search',

From 829186c703ff66b55b062d231a00792cee3949fe Mon Sep 17 00:00:00 2001
From: slorber <lorber.sebastien@gmail.com>
Date: Wed, 10 Jun 2020 17:35:03 +0200
Subject: [PATCH 16/16] add useful comment

---
 packages/docusaurus-plugin-content-docs/src/metadata.ts | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/packages/docusaurus-plugin-content-docs/src/metadata.ts b/packages/docusaurus-plugin-content-docs/src/metadata.ts
index a86d028954fa..60ad3d959dd4 100644
--- a/packages/docusaurus-plugin-content-docs/src/metadata.ts
+++ b/packages/docusaurus-plugin-content-docs/src/metadata.ts
@@ -148,7 +148,8 @@ export default async function processMetadata({
   let routePath;
   if (isDocsHomePage) {
     // TODO can we remove this trailing / ?
-    // Seems it's not that easy... the sidebar disappears on homepage xD
+    // Seems it's not that easy...
+    // Related to https://github.com/facebook/docusaurus/issues/2917
     routePath = '/';
   } else {
     routePath =