@docusaurus/plugin-content-docs 2.0.0-beta.0e652730d → 2.0.0-beta.10

package/src/__tests__/docs.test.ts

@@ -7,21 +7,29 @@
 
 import path from 'path';
 import {loadContext} from '@docusaurus/core/src/server/index';
-import {processDocMetadata, readVersionDocs, readDocFile} from '../docs';
-import {readVersionsMetadata} from '../versions';
 import {
+  processDocMetadata,
+  readVersionDocs,
+  readDocFile,
+  addDocNavigation,
+  isConventionalDocIndex,
+} from '../docs';
+import {loadSidebars} from '../sidebars';
+import {readVersionsMetadata} from '../versions';
+import type {
   DocFile,
   DocMetadataBase,
   MetadataOptions,
   VersionMetadata,
   PluginOptions,
   EditUrlFunction,
+  DocNavLink,
 } from '../types';
-import {LoadContext} from '@docusaurus/types';
-import {DEFAULT_PLUGIN_ID} from '@docusaurus/core/lib/constants';
+import type {LoadContext} from '@docusaurus/types';
 import {DEFAULT_OPTIONS} from '../options';
 import {Optional} from 'utility-types';
-import {posixPath} from '@docusaurus/utils';
+import {createSlugger, posixPath, DEFAULT_PLUGIN_ID} from '@docusaurus/utils';
+import {createSidebarsUtils} from '../sidebars/utils';
 
 const fixtureDir = path.join(__dirname, '__fixtures__');
 
@@ -110,7 +118,41 @@ function createTestUtils({
     expect(metadata.permalink).toEqual(expectedPermalink);
   }
 
-  return {processDocFile, testMeta, testSlug};
+  async function generateNavigation(
+    docFiles: DocFile[],
+  ): Promise<[DocNavLink | undefined, DocNavLink | undefined][]> {
+    const rawDocs = await Promise.all(
+      docFiles.map((docFile) =>
+        processDocMetadata({
+          docFile,
+          versionMetadata,
+          context,
+          options,
+        }),
+      ),
+    );
+    const sidebars = await loadSidebars(versionMetadata.sidebarFilePath, {
+      sidebarItemsGenerator: ({defaultSidebarItemsGenerator, ...args}) =>
+        defaultSidebarItemsGenerator({...args}),
+      numberPrefixParser: options.numberPrefixParser,
+      docs: rawDocs,
+      version: versionMetadata,
+      sidebarOptions: {
+        sidebarCollapsed: false,
+        sidebarCollapsible: true,
+      },
+      categoryLabelSlugger: createSlugger(),
+    });
+    const sidebarsUtils = createSidebarsUtils(sidebars);
+
+    return addDocNavigation(
+      rawDocs,
+      sidebarsUtils,
+      versionMetadata.sidebarFilePath as string,
+    ).map((doc) => [doc.previous, doc.next]);
+  }
+
+  return {processDocFile, testMeta, testSlug, generateNavigation};
 }
 
 describe('simple site', () => {
@@ -177,7 +219,6 @@ describe('simple site', () => {
       id: 'foo/bar',
       unversionedId: 'foo/bar',
       sourceDirName: 'foo',
-      isDocsHomePage: false,
       permalink: '/docs/foo/bar',
       slug: '/foo/bar',
       title: 'Bar',
@@ -187,43 +228,13 @@ describe('simple site', () => {
         id: 'bar',
         title: 'Bar',
       },
+      tags: [],
     });
     await defaultTestUtils.testMeta(path.join('hello.md'), {
       version: 'current',
       id: 'hello',
       unversionedId: 'hello',
       sourceDirName: '.',
-      isDocsHomePage: false,
-      permalink: '/docs/hello',
-      slug: '/hello',
-      title: 'Hello, World !',
-      description: `Hi, Endilie here :)`,
-      frontMatter: {
-        id: 'hello',
-        title: 'Hello, World !',
-        sidebar_label: 'Hello sidebar_label',
-      },
-    });
-  });
-
-  test('homePageId doc', async () => {
-    const {siteDir, context, options, currentVersion} = await loadSite({
-      options: {homePageId: 'hello'},
-    });
-
-    const testUtilsLocal = createTestUtils({
-      siteDir,
-      context,
-      options,
-      versionMetadata: currentVersion,
-    });
-
-    await testUtilsLocal.testMeta(path.join('hello.md'), {
-      version: 'current',
-      id: 'hello',
-      unversionedId: 'hello',
-      sourceDirName: '.',
-      isDocsHomePage: true,
       permalink: '/docs/',
       slug: '/',
       title: 'Hello, World !',
@@ -232,44 +243,26 @@ describe('simple site', () => {
         id: 'hello',
         title: 'Hello, World !',
         sidebar_label: 'Hello sidebar_label',
+        slug: '/',
+        tags: ['tag-1', 'tag 3'],
       },
-    });
-  });
-
-  test('homePageId doc nested', async () => {
-    const {siteDir, context, options, currentVersion} = await loadSite({
-      options: {homePageId: 'foo/bar'},
-    });
-
-    const testUtilsLocal = createTestUtils({
-      siteDir,
-      context,
-      options,
-      versionMetadata: currentVersion,
-    });
-
-    await testUtilsLocal.testMeta(path.join('foo', 'bar.md'), {
-      version: 'current',
-      id: 'foo/bar',
-      unversionedId: 'foo/bar',
-      sourceDirName: 'foo',
-      isDocsHomePage: true,
-      permalink: '/docs/',
-      slug: '/',
-      title: 'Bar',
-      description: 'This is custom description',
-      frontMatter: {
-        description: 'This is custom description',
-        id: 'bar',
-        title: 'Bar',
-      },
+      tags: [
+        {
+          label: 'tag-1',
+          permalink: '/docs/tags/tag-1',
+        },
+        {
+          label: 'tag 3',
+          permalink: '/docs/tags/tag-3',
+        },
+      ],
     });
   });
 
   test('docs with editUrl', async () => {
     const {siteDir, context, options, currentVersion} = await loadSite({
       options: {
-        editUrl: 'https://github.com/facebook/docusaurus/edit/master/website',
+        editUrl: 'https://github.com/facebook/docusaurus/edit/main/website',
       },
     });
 
@@ -285,19 +278,33 @@ describe('simple site', () => {
       id: 'foo/baz',
       unversionedId: 'foo/baz',
       sourceDirName: 'foo',
-      isDocsHomePage: false,
       permalink: '/docs/foo/bazSlug.html',
       slug: '/foo/bazSlug.html',
       title: 'baz',
       editUrl:
-        'https://github.com/facebook/docusaurus/edit/master/website/docs/foo/baz.md',
+        'https://github.com/facebook/docusaurus/edit/main/website/docs/foo/baz.md',
       description: 'Images',
       frontMatter: {
         id: 'baz',
         slug: 'bazSlug.html',
         title: 'baz',
         pagination_label: 'baz pagination_label',
+        tags: [
+          'tag 1',
+          'tag-1',
+          {label: 'tag 2', permalink: 'tag2-custom-permalink'},
+        ],
       },
+      tags: [
+        {
+          label: 'tag 1',
+          permalink: '/docs/tags/tag-1',
+        },
+        {
+          label: 'tag 2',
+          permalink: '/docs/tags/tag2-custom-permalink',
+        },
+      ],
     });
   });
 
@@ -309,7 +316,6 @@ describe('simple site', () => {
       id: 'lorem',
       unversionedId: 'lorem',
       sourceDirName: '.',
-      isDocsHomePage: false,
       permalink: '/docs/lorem',
       slug: '/lorem',
       title: 'lorem',
@@ -319,6 +325,7 @@ describe('simple site', () => {
         custom_edit_url: 'https://github.com/customUrl/docs/lorem.md',
         unrelated_frontmatter: "won't be part of metadata",
       },
+      tags: [],
     });
   });
 
@@ -345,7 +352,6 @@ describe('simple site', () => {
       id: 'foo/baz',
       unversionedId: 'foo/baz',
       sourceDirName: 'foo',
-      isDocsHomePage: false,
       permalink: '/docs/foo/bazSlug.html',
       slug: '/foo/bazSlug.html',
       title: 'baz',
@@ -356,7 +362,22 @@ describe('simple site', () => {
         slug: 'bazSlug.html',
         title: 'baz',
         pagination_label: 'baz pagination_label',
+        tags: [
+          'tag 1',
+          'tag-1',
+          {label: 'tag 2', permalink: 'tag2-custom-permalink'},
+        ],
       },
+      tags: [
+        {
+          label: 'tag 1',
+          permalink: '/docs/tags/tag-1',
+        },
+        {
+          label: 'tag 2',
+          permalink: '/docs/tags/tag2-custom-permalink',
+        },
+      ],
     });
 
     expect(editUrlFunction).toHaveBeenCalledTimes(1);
@@ -389,7 +410,6 @@ describe('simple site', () => {
       id: 'lorem',
       unversionedId: 'lorem',
       sourceDirName: '.',
-      isDocsHomePage: false,
       permalink: '/docs/lorem',
       slug: '/lorem',
       title: 'lorem',
@@ -402,6 +422,7 @@ describe('simple site', () => {
       lastUpdatedAt: 1539502055,
       formattedLastUpdatedAt: '10/14/2018',
       lastUpdatedBy: 'Author',
+      tags: [],
     });
   });
 
@@ -459,30 +480,25 @@ describe('simple site', () => {
     );
   });
 
-  test('docs with slug on doc home', async () => {
-    const {siteDir, context, options, currentVersion} = await loadSite({
-      options: {
-        homePageId: 'homePageId',
-      },
-    });
+  test('custom pagination', async () => {
+    const {defaultTestUtils, options, versionsMetadata} = await loadSite();
+    const docs = await readVersionDocs(versionsMetadata[0], options);
+    expect(await defaultTestUtils.generateNavigation(docs)).toMatchSnapshot();
+  });
 
-    const testUtilsLocal = createTestUtils({
-      siteDir,
-      context,
-      options,
-      versionMetadata: currentVersion,
-    });
-    expect(() => {
-      testUtilsLocal.processDocFile(
-        createFakeDocFile({
-          source: 'homePageId',
-          frontmatter: {
-            slug: '/x/y',
-          },
-        }),
-      );
-    }).toThrowErrorMatchingInlineSnapshot(
-      `"The docs homepage (homePageId=homePageId) is not allowed to have a frontmatter slug=/x/y => you have to choose either homePageId or slug, not both"`,
+  test('bad pagination', async () => {
+    const {defaultTestUtils, options, versionsMetadata} = await loadSite();
+    const docs = await readVersionDocs(versionsMetadata[0], options);
+    docs.push(
+      createFakeDocFile({
+        source: 'hehe',
+        frontmatter: {pagination_prev: 'nonexistent'},
+      }),
+    );
+    await expect(async () => {
+      await defaultTestUtils.generateNavigation(docs);
+    }).rejects.toThrowErrorMatchingInlineSnapshot(
+      `"Error when loading hehe in .: the pagination_prev front matter points to a non-existent ID nonexistent."`,
     );
   });
 });
@@ -507,12 +523,8 @@ describe('versioned site', () => {
       options,
     });
     expect(versionsMetadata.length).toEqual(4);
-    const [
-      currentVersion,
-      version101,
-      version100,
-      versionWithSlugs,
-    ] = versionsMetadata;
+    const [currentVersion, version101, version100, versionWithSlugs] =
+      versionsMetadata;
 
     const currentVersionTestUtils = createTestUtils({
       siteDir,
@@ -559,27 +571,52 @@ describe('versioned site', () => {
 
     await currentVersionTestUtils.testMeta(path.join('foo', 'bar.md'), {
       id: 'foo/bar',
+      version: 'current',
       unversionedId: 'foo/bar',
       sourceDirName: 'foo',
-      isDocsHomePage: false,
       permalink: '/docs/next/foo/barSlug',
       slug: '/foo/barSlug',
       title: 'bar',
       description: 'This is next version of bar.',
-      frontMatter: {slug: 'barSlug'},
-      version: 'current',
+      frontMatter: {
+        slug: 'barSlug',
+        tags: [
+          'barTag 1',
+          'barTag-2',
+          {
+            label: 'barTag 3',
+            permalink: 'barTag-3-permalink',
+          },
+        ],
+      },
+      tags: [
+        {
+          label: 'barTag 1',
+          permalink: '/docs/next/tags/bar-tag-1',
+        },
+        {
+          label: 'barTag-2',
+          permalink: '/docs/next/tags/bar-tag-2',
+        },
+        {
+          label: 'barTag 3',
+          permalink: '/docs/next/tags/barTag-3-permalink',
+        },
+      ],
     });
     await currentVersionTestUtils.testMeta(path.join('hello.md'), {
       id: 'hello',
+      version: 'current',
       unversionedId: 'hello',
       sourceDirName: '.',
-      isDocsHomePage: false,
-      permalink: '/docs/next/hello',
-      slug: '/hello',
+      permalink: '/docs/next/',
+      slug: '/',
       title: 'hello',
       description: 'Hello next !',
-      frontMatter: {},
-      version: 'current',
+      frontMatter: {
+        slug: '/',
+      },
+      tags: [],
     });
   });
 
@@ -590,51 +627,55 @@ describe('versioned site', () => {
       id: 'version-1.0.0/foo/bar',
       unversionedId: 'foo/bar',
       sourceDirName: 'foo',
-      isDocsHomePage: false,
       permalink: '/docs/1.0.0/foo/barSlug',
       slug: '/foo/barSlug',
       title: 'bar',
       description: 'Bar 1.0.0 !',
       frontMatter: {slug: 'barSlug'},
       version: '1.0.0',
+      tags: [],
     });
     await version100TestUtils.testMeta(path.join('hello.md'), {
       id: 'version-1.0.0/hello',
       unversionedId: 'hello',
       sourceDirName: '.',
-      isDocsHomePage: false,
-      permalink: '/docs/1.0.0/hello',
-      slug: '/hello',
+      permalink: '/docs/1.0.0/',
+      slug: '/',
       title: 'hello',
       description: 'Hello 1.0.0 ! (translated en)',
-      frontMatter: {},
+      frontMatter: {
+        slug: '/',
+      },
       version: '1.0.0',
       source:
         '@site/i18n/en/docusaurus-plugin-content-docs/version-1.0.0/hello.md',
+      tags: [],
     });
     await version101TestUtils.testMeta(path.join('foo', 'bar.md'), {
       id: 'version-1.0.1/foo/bar',
       unversionedId: 'foo/bar',
       sourceDirName: 'foo',
-      isDocsHomePage: false,
       permalink: '/docs/foo/bar',
       slug: '/foo/bar',
       title: 'bar',
       description: 'Bar 1.0.1 !',
       version: '1.0.1',
       frontMatter: {},
+      tags: [],
     });
     await version101TestUtils.testMeta(path.join('hello.md'), {
       id: 'version-1.0.1/hello',
       unversionedId: 'hello',
       sourceDirName: '.',
-      isDocsHomePage: false,
-      permalink: '/docs/hello',
-      slug: '/hello',
+      permalink: '/docs/',
+      slug: '/',
       title: 'hello',
       description: 'Hello 1.0.1 !',
       version: '1.0.1',
-      frontMatter: {},
+      frontMatter: {
+        slug: '/',
+      },
+      tags: [],
     });
   });
 
@@ -719,16 +760,18 @@ describe('versioned site', () => {
       id: 'version-1.0.0/hello',
       unversionedId: 'hello',
       sourceDirName: '.',
-      isDocsHomePage: false,
-      permalink: '/docs/1.0.0/hello',
-      slug: '/hello',
+      permalink: '/docs/1.0.0/',
+      slug: '/',
       title: 'hello',
       description: 'Hello 1.0.0 ! (translated en)',
-      frontMatter: {},
+      frontMatter: {
+        slug: '/',
+      },
       version: '1.0.0',
       source:
         '@site/i18n/en/docusaurus-plugin-content-docs/version-1.0.0/hello.md',
       editUrl: hardcodedEditUrl,
+      tags: [],
     });
 
     expect(editUrlFunction).toHaveBeenCalledTimes(1);
@@ -736,7 +779,7 @@ describe('versioned site', () => {
       version: '1.0.0',
       versionDocsDirPath: 'versioned_docs/version-1.0.0',
       docPath: path.join('hello.md'),
-      permalink: '/docs/1.0.0/hello',
+      permalink: '/docs/1.0.0/',
       locale: 'en',
     });
   });
@@ -744,7 +787,7 @@ describe('versioned site', () => {
   test('translated doc with editUrl', async () => {
     const {siteDir, context, options, version100} = await loadSite({
       options: {
-        editUrl: 'https://github.com/facebook/docusaurus/edit/master/website',
+        editUrl: 'https://github.com/facebook/docusaurus/edit/main/website',
         // editCurrentVersion: true,
       },
     });
@@ -760,24 +803,26 @@ describe('versioned site', () => {
       id: 'version-1.0.0/hello',
       unversionedId: 'hello',
       sourceDirName: '.',
-      isDocsHomePage: false,
-      permalink: '/docs/1.0.0/hello',
-      slug: '/hello',
+      permalink: '/docs/1.0.0/',
+      slug: '/',
       title: 'hello',
       description: 'Hello 1.0.0 ! (translated en)',
-      frontMatter: {},
+      frontMatter: {
+        slug: '/',
+      },
       version: '1.0.0',
       source:
         '@site/i18n/en/docusaurus-plugin-content-docs/version-1.0.0/hello.md',
       editUrl:
-        'https://github.com/facebook/docusaurus/edit/master/website/versioned_docs/version-1.0.0/hello.md',
+        'https://github.com/facebook/docusaurus/edit/main/website/versioned_docs/version-1.0.0/hello.md',
+      tags: [],
     });
   });
 
   test('translated en doc with editUrl and editCurrentVersion=true', async () => {
     const {siteDir, context, options, version100} = await loadSite({
       options: {
-        editUrl: 'https://github.com/facebook/docusaurus/edit/master/website',
+        editUrl: 'https://github.com/facebook/docusaurus/edit/main/website',
         editCurrentVersion: true,
       },
     });
@@ -793,24 +838,26 @@ describe('versioned site', () => {
       id: 'version-1.0.0/hello',
       unversionedId: 'hello',
       sourceDirName: '.',
-      isDocsHomePage: false,
-      permalink: '/docs/1.0.0/hello',
-      slug: '/hello',
+      permalink: '/docs/1.0.0/',
+      slug: '/',
       title: 'hello',
       description: 'Hello 1.0.0 ! (translated en)',
-      frontMatter: {},
+      frontMatter: {
+        slug: '/',
+      },
       version: '1.0.0',
       source:
         '@site/i18n/en/docusaurus-plugin-content-docs/version-1.0.0/hello.md',
       editUrl:
-        'https://github.com/facebook/docusaurus/edit/master/website/docs/hello.md',
+        'https://github.com/facebook/docusaurus/edit/main/website/docs/hello.md',
+      tags: [],
     });
   });
 
   test('translated fr doc with editUrl and editLocalizedFiles=true', async () => {
     const {siteDir, context, options, version100} = await loadSite({
       options: {
-        editUrl: 'https://github.com/facebook/docusaurus/edit/master/website',
+        editUrl: 'https://github.com/facebook/docusaurus/edit/main/website',
         editLocalizedFiles: true,
       },
       locale: 'fr',
@@ -827,24 +874,26 @@ describe('versioned site', () => {
       id: 'version-1.0.0/hello',
       unversionedId: 'hello',
       sourceDirName: '.',
-      isDocsHomePage: false,
-      permalink: '/fr/docs/1.0.0/hello',
-      slug: '/hello',
+      permalink: '/fr/docs/1.0.0/',
+      slug: '/',
       title: 'hello',
       description: 'Hello 1.0.0 ! (translated fr)',
-      frontMatter: {},
+      frontMatter: {
+        slug: '/',
+      },
       version: '1.0.0',
       source:
         '@site/i18n/fr/docusaurus-plugin-content-docs/version-1.0.0/hello.md',
       editUrl:
-        'https://github.com/facebook/docusaurus/edit/master/website/i18n/fr/docusaurus-plugin-content-docs/version-1.0.0/hello.md',
+        'https://github.com/facebook/docusaurus/edit/main/website/i18n/fr/docusaurus-plugin-content-docs/version-1.0.0/hello.md',
+      tags: [],
     });
   });
 
   test('translated fr doc with editUrl and editLocalizedFiles=true + editCurrentVersion=true', async () => {
     const {siteDir, context, options, version100} = await loadSite({
       options: {
-        editUrl: 'https://github.com/facebook/docusaurus/edit/master/website',
+        editUrl: 'https://github.com/facebook/docusaurus/edit/main/website',
         editCurrentVersion: true,
         editLocalizedFiles: true,
       },
@@ -862,17 +911,129 @@ describe('versioned site', () => {
       id: 'version-1.0.0/hello',
       unversionedId: 'hello',
       sourceDirName: '.',
-      isDocsHomePage: false,
-      permalink: '/fr/docs/1.0.0/hello',
-      slug: '/hello',
+      permalink: '/fr/docs/1.0.0/',
+      slug: '/',
       title: 'hello',
       description: 'Hello 1.0.0 ! (translated fr)',
-      frontMatter: {},
+      frontMatter: {
+        slug: '/',
+      },
       version: '1.0.0',
       source:
         '@site/i18n/fr/docusaurus-plugin-content-docs/version-1.0.0/hello.md',
       editUrl:
-        'https://github.com/facebook/docusaurus/edit/master/website/i18n/fr/docusaurus-plugin-content-docs/current/hello.md',
+        'https://github.com/facebook/docusaurus/edit/main/website/i18n/fr/docusaurus-plugin-content-docs/current/hello.md',
+      tags: [],
     });
   });
 });
+
+describe('isConventionalDocIndex', () => {
+  test('supports readme', () => {
+    expect(
+      isConventionalDocIndex({
+        sourceDirName: 'doesNotMatter',
+        source: 'readme.md',
+      }),
+    ).toEqual(true);
+    expect(
+      isConventionalDocIndex({
+        sourceDirName: 'doesNotMatter',
+        source: 'readme.mdx',
+      }),
+    ).toEqual(true);
+    expect(
+      isConventionalDocIndex({
+        sourceDirName: 'doesNotMatter',
+        source: 'README.md',
+      }),
+    ).toEqual(true);
+    expect(
+      isConventionalDocIndex({
+        sourceDirName: 'doesNotMatter',
+        source: 'parent/ReAdMe',
+      }),
+    ).toEqual(true);
+  });
+
+  test('supports index', () => {
+    expect(
+      isConventionalDocIndex({
+        sourceDirName: 'doesNotMatter',
+        source: 'index.md',
+      }),
+    ).toEqual(true);
+    expect(
+      isConventionalDocIndex({
+        sourceDirName: 'doesNotMatter',
+        source: 'index.mdx',
+      }),
+    ).toEqual(true);
+    expect(
+      isConventionalDocIndex({
+        sourceDirName: 'doesNotMatter',
+        source: 'INDEX.md',
+      }),
+    ).toEqual(true);
+    expect(
+      isConventionalDocIndex({
+        sourceDirName: 'doesNotMatter',
+        source: 'parent/InDeX',
+      }),
+    ).toEqual(true);
+  });
+
+  test('supports <categoryName>/<categoryName>.md', () => {
+    expect(
+      isConventionalDocIndex({
+        sourceDirName: 'someCategory',
+        source: 'someCategory',
+      }),
+    ).toEqual(true);
+    expect(
+      isConventionalDocIndex({
+        sourceDirName: 'someCategory',
+        source: 'someCategory.md',
+      }),
+    ).toEqual(true);
+    expect(
+      isConventionalDocIndex({
+        sourceDirName: 'someCategory',
+        source: 'someCategory.mdx',
+      }),
+    ).toEqual(true);
+    expect(
+      isConventionalDocIndex({
+        sourceDirName: 'some_category',
+        source: 'SOME_CATEGORY.md',
+      }),
+    ).toEqual(true);
+    expect(
+      isConventionalDocIndex({
+        sourceDirName: 'some_category',
+        source: 'parent/some_category',
+      }),
+    ).toEqual(true);
+  });
+
+  test('reject other cases', () => {
+    expect(
+      isConventionalDocIndex({
+        sourceDirName: 'someCategory',
+        source: 'some_Category',
+      }),
+    ).toEqual(false);
+    expect(
+      isConventionalDocIndex({
+        sourceDirName: 'doesNotMatter',
+        source: 'read_me',
+      }),
+    ).toEqual(false);
+    expect(
+      isConventionalDocIndex({
+        sourceDirName: 'doesNotMatter',
+        source: 'the index',
+      }),
+    ).toEqual(false);
+  });
+});