fix(v2): fix docs homepage permalink issues (#2905)

* better fixes for docs homepage

* fix tests

* create special route for docs homepage + cleanup existing code

* no need to create multiple docs parent paths

* useful comment

* add test for slug + doc home usage at the same time error

* remove confusing variable name

* fix tests by using same suffix as before for docs base metadata path

* metadata: use homePageId correctly for nested docs: the full docId (including /) should be used to compare against homePageId

* add folder/testNested test doc

* refactor a bit processMetadata, the home should be handled correctly for all versions

* 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

* revert homePageId

* remove test doc

* remove test doc

* add useful comment

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',
@@ -168,6 +169,7 @@ describe('simple website', () => {
 
     expect(docsMetadata['foo/bar']).toEqual({
       id: 'foo/bar',
+      isDocsHomePage: false,
       next: {
         title: 'baz',
         permalink: '/docs/foo/bazSlug.html',
@@ -296,6 +298,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',
@@ -304,12 +307,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 !',
@@ -322,7 +326,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),
@@ -341,6 +346,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',
@@ -356,7 +362,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',