@docusaurus/plugin-content-docs 2.0.0-beta.8e9b829d9 → 2.0.0-beta.9

package/src/__tests__/docs.test.ts

@@ -7,7 +7,13 @@
 
 import path from 'path';
 import {loadContext} from '@docusaurus/core/src/server/index';
-import {processDocMetadata, readVersionDocs, readDocFile} from '../docs';
+import {
+  processDocMetadata,
+  readVersionDocs,
+  readDocFile,
+  handleNavigation,
+} from '../docs';
+import {loadSidebars} from '../sidebars';
 import {readVersionsMetadata} from '../versions';
 import {
   DocFile,
@@ -16,6 +22,7 @@ import {
   VersionMetadata,
   PluginOptions,
   EditUrlFunction,
+  DocNavLink,
 } from '../types';
 import {LoadContext} from '@docusaurus/types';
 import {DEFAULT_PLUGIN_ID} from '@docusaurus/core/lib/constants';
@@ -110,7 +117,38 @@ function createTestUtils({
     expect(metadata.permalink).toEqual(expectedPermalink);
   }
 
-  return {processDocFile, testMeta, testSlug};
+  async function generateNavigation(
+    docFiles: DocFile[],
+  ): Promise<[DocNavLink, DocNavLink][]> {
+    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,
+      options: {
+        sidebarCollapsed: false,
+        sidebarCollapsible: true,
+      },
+    });
+    return handleNavigation(
+      rawDocs,
+      sidebars,
+      versionMetadata.sidebarFilePath as string,
+    ).docs.map((doc) => [doc.previous, doc.next]);
+  }
+
+  return {processDocFile, testMeta, testSlug, generateNavigation};
 }
 
 describe('simple site', () => {
@@ -187,6 +225,7 @@ describe('simple site', () => {
         id: 'bar',
         title: 'Bar',
       },
+      tags: [],
     });
     await defaultTestUtils.testMeta(path.join('hello.md'), {
       version: 'current',
@@ -202,7 +241,18 @@ describe('simple site', () => {
         id: 'hello',
         title: 'Hello, World !',
         sidebar_label: 'Hello sidebar_label',
+        tags: ['tag-1', 'tag 3'],
       },
+      tags: [
+        {
+          label: 'tag-1',
+          permalink: '/docs/tags/tag-1',
+        },
+        {
+          label: 'tag 3',
+          permalink: '/docs/tags/tag-3',
+        },
+      ],
     });
   });
 
@@ -232,7 +282,18 @@ describe('simple site', () => {
         id: 'hello',
         title: 'Hello, World !',
         sidebar_label: 'Hello sidebar_label',
+        tags: ['tag-1', 'tag 3'],
       },
+      tags: [
+        {
+          label: 'tag-1',
+          permalink: '/docs/tags/tag-1',
+        },
+        {
+          label: 'tag 3',
+          permalink: '/docs/tags/tag-3',
+        },
+      ],
     });
   });
 
@@ -263,13 +324,14 @@ describe('simple site', () => {
         id: 'bar',
         title: 'Bar',
       },
+      tags: [],
     });
   });
 
   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',
       },
     });
 
@@ -290,14 +352,29 @@ describe('simple site', () => {
       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',
+        },
+      ],
     });
   });
 
@@ -319,6 +396,7 @@ describe('simple site', () => {
         custom_edit_url: 'https://github.com/customUrl/docs/lorem.md',
         unrelated_frontmatter: "won't be part of metadata",
       },
+      tags: [],
     });
   });
 
@@ -356,7 +434,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);
@@ -402,6 +495,7 @@ describe('simple site', () => {
       lastUpdatedAt: 1539502055,
       formattedLastUpdatedAt: '10/14/2018',
       lastUpdatedBy: 'Author',
+      tags: [],
     });
   });
 
@@ -485,6 +579,28 @@ describe('simple site', () => {
       `"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('custom pagination', async () => {
+    const {defaultTestUtils, options, versionsMetadata} = await loadSite();
+    const docs = await readVersionDocs(versionsMetadata[0], options);
+    expect(await defaultTestUtils.generateNavigation(docs)).toMatchSnapshot();
+  });
+
+  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."`,
+    );
+  });
 });
 
 describe('versioned site', () => {
@@ -507,12 +623,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,6 +671,7 @@ describe('versioned site', () => {
 
     await currentVersionTestUtils.testMeta(path.join('foo', 'bar.md'), {
       id: 'foo/bar',
+      version: 'current',
       unversionedId: 'foo/bar',
       sourceDirName: 'foo',
       isDocsHomePage: false,
@@ -566,11 +679,35 @@ describe('versioned site', () => {
       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,
@@ -579,7 +716,7 @@ describe('versioned site', () => {
       title: 'hello',
       description: 'Hello next !',
       frontMatter: {},
-      version: 'current',
+      tags: [],
     });
   });
 
@@ -597,6 +734,7 @@ describe('versioned site', () => {
       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',
@@ -611,6 +749,7 @@ describe('versioned site', () => {
       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',
@@ -623,6 +762,7 @@ describe('versioned site', () => {
       description: 'Bar 1.0.1 !',
       version: '1.0.1',
       frontMatter: {},
+      tags: [],
     });
     await version101TestUtils.testMeta(path.join('hello.md'), {
       id: 'version-1.0.1/hello',
@@ -635,6 +775,7 @@ describe('versioned site', () => {
       description: 'Hello 1.0.1 !',
       version: '1.0.1',
       frontMatter: {},
+      tags: [],
     });
   });
 
@@ -729,6 +870,7 @@ describe('versioned site', () => {
       source:
         '@site/i18n/en/docusaurus-plugin-content-docs/version-1.0.0/hello.md',
       editUrl: hardcodedEditUrl,
+      tags: [],
     });
 
     expect(editUrlFunction).toHaveBeenCalledTimes(1);
@@ -744,7 +886,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,
       },
     });
@@ -770,14 +912,15 @@ describe('versioned site', () => {
       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,
       },
     });
@@ -803,14 +946,15 @@ describe('versioned site', () => {
       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',
@@ -837,14 +981,15 @@ describe('versioned site', () => {
       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,
       },
@@ -872,7 +1017,8 @@ describe('versioned site', () => {
       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: [],
     });
   });
 });

package/src/__tests__/index.test.ts

@@ -5,8 +5,6 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-/* eslint-disable @typescript-eslint/no-non-null-assertion */
-
 import path from 'path';
 import {isMatch} from 'picomatch';
 import commander from 'commander';
@@ -24,17 +22,16 @@ import {DEFAULT_PLUGIN_ID} from '@docusaurus/core/lib/constants';
 import * as cliDocs from '../cli';
 import {OptionsSchema} from '../options';
 import {normalizePluginOptions} from '@docusaurus/utils-validation';
-import {
-  DocMetadata,
-  LoadedVersion,
+import type {DocMetadata, LoadedVersion} from '../types';
+import type {
   SidebarItem,
   SidebarItemsGeneratorOption,
   SidebarItemsGeneratorOptionArgs,
-} from '../types';
+} from '../sidebars/types';
 import {toSidebarsProp} from '../props';
 
 import {validate} from 'webpack';
-import {DefaultSidebarItemsGenerator} from '../sidebarItemsGenerator';
+import {DefaultSidebarItemsGenerator} from '../sidebars/generator';
 import {DisabledSidebars} from '../sidebars';
 
 function findDocById(version: LoadedVersion, unversionedId: string) {
@@ -60,6 +57,7 @@ const defaultDocMetadata: Partial<DocMetadata> = {
   lastUpdatedAt: undefined,
   lastUpdatedBy: undefined,
   formattedLastUpdatedAt: undefined,
+  tags: [],
 };
 
 const createFakeActions = (contentDir: string) => {
@@ -347,10 +345,11 @@ describe('simple website', () => {
         permalink: '/docs/foo/bar',
       },
       next: {
-        title: 'Hello sidebar_label',
-        permalink: '/docs/',
+        title: 'rootAbsoluteSlug',
+        permalink: '/docs/rootAbsoluteSlug',
       },
       sidebar: 'docs',
+      sidebarPosition: undefined,
       source: path.posix.join(
         '@site',
         posixPath(path.relative(siteDir, currentVersion.contentPath)),
@@ -364,7 +363,23 @@ describe('simple website', () => {
         title: 'baz',
         slug: 'bazSlug.html',
         pagination_label: 'baz pagination_label',
+        tags: [
+          'tag 1',
+          'tag-1', // This one will be de-duplicated as it would lead to the same permalink as the first
+          {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(findDocById(currentVersion, 'hello')).toEqual({
@@ -377,8 +392,8 @@ describe('simple website', () => {
       permalink: '/docs/',
       slug: '/',
       previous: {
-        title: 'baz pagination_label',
-        permalink: '/docs/foo/bazSlug.html',
+        title: 'My heading as title',
+        permalink: '/docs/headingAsTitle',
       },
       sidebar: 'docs',
       source: path.posix.join(
@@ -392,7 +407,18 @@ describe('simple website', () => {
         id: 'hello',
         title: 'Hello, World !',
         sidebar_label: 'Hello sidebar_label',
+        tags: ['tag-1', 'tag 3'],
       },
+      tags: [
+        {
+          label: 'tag-1',
+          permalink: '/docs/tags/tag-1',
+        },
+        {
+          label: 'tag 3',
+          permalink: '/docs/tags/tag-3',
+        },
+      ],
     });
 
     expect(getDocById(currentVersion, 'foo/bar')).toEqual({
@@ -549,12 +575,8 @@ describe('versioned website', () => {
     const {siteDir, plugin, pluginContentDir} = await loadSite();
     const content = await plugin.loadContent!();
     expect(content.loadedVersions.length).toEqual(4);
-    const [
-      currentVersion,
-      version101,
-      version100,
-      versionWithSlugs,
-    ] = content.loadedVersions;
+    const [currentVersion, version101, version100, versionWithSlugs] =
+      content.loadedVersions;
 
     // foo/baz.md only exists in version -1.0.0
     expect(findDocById(currentVersion, 'foo/baz')).toBeUndefined();
@@ -579,6 +601,11 @@ describe('versioned website', () => {
       description: 'This is next version of bar.',
       frontMatter: {
         slug: 'barSlug',
+        tags: [
+          'barTag 1',
+          'barTag-2',
+          {label: 'barTag 3', permalink: 'barTag-3-permalink'},
+        ],
       },
       version: 'current',
       sidebar: 'docs',
@@ -586,6 +613,11 @@ describe('versioned website', () => {
         title: 'hello',
         permalink: '/docs/next/',
       },
+      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'},
+      ],
     });
     expect(getDocById(currentVersion, 'hello')).toEqual({
       ...defaultDocMetadata,
@@ -715,13 +747,8 @@ describe('versioned website (community)', () => {
   }
 
   test('extendCli - docsVersion', async () => {
-    const {
-      siteDir,
-      routeBasePath,
-      sidebarPath,
-      pluginId,
-      plugin,
-    } = await loadSite();
+    const {siteDir, routeBasePath, sidebarPath, pluginId, plugin} =
+      await loadSite();
     const mock = jest
       .spyOn(cliDocs, 'cliDocsVersionCommand')
       .mockImplementation();
@@ -1748,12 +1775,11 @@ describe('site with custom sidebar items generator', () => {
   });
 
   test('sidebar is autogenerated according to a custom sidebarItemsGenerator', async () => {
-    const customSidebarItemsGenerator: SidebarItemsGeneratorOption = async () => {
-      return [
+    const customSidebarItemsGenerator: SidebarItemsGeneratorOption =
+      async () => [
         {type: 'doc', id: 'API/api-overview'},
         {type: 'doc', id: 'API/api-end'},
       ];
-    };
 
     const {content} = await loadSite(customSidebarItemsGenerator);
     const version = content.loadedVersions[0];

package/src/__tests__/options.test.ts

@@ -7,7 +7,7 @@
 
 import {OptionsSchema, DEFAULT_OPTIONS, validateOptions} from '../options';
 import {normalizePluginOptions} from '@docusaurus/utils-validation';
-import {DefaultSidebarItemsGenerator} from '../sidebarItemsGenerator';
+import {DefaultSidebarItemsGenerator} from '../sidebars/generator';
 import {
   DefaultNumberPrefixParser,
   DisabledNumberPrefixParser,
@@ -40,6 +40,7 @@ describe('normalizeDocsPluginOptions', () => {
     const userOptions = {
       path: 'my-docs', // Path to data on filesystem, relative to site dir.
       routeBasePath: 'my-docs', // URL Route.
+      tagsBasePath: 'tags', // URL Tags Route.
       homePageId: 'home', // Document id for docs home page.
       include: ['**/*.{md,mdx}'], // Extensions to include.
       exclude: GlobExcludeDefault,
@@ -48,6 +49,8 @@ describe('normalizeDocsPluginOptions', () => {
       numberPrefixParser: DefaultNumberPrefixParser,
       docLayoutComponent: '@theme/DocPage',
       docItemComponent: '@theme/DocItem',
+      docTagDocListComponent: '@theme/DocTagDocListPage',
+      docTagsListComponent: '@theme/DocTagsListPage',
       remarkPlugins: [markdownPluginsObjectStub],
       rehypePlugins: [markdownPluginsFunctionStub],
       beforeDefaultRehypePlugins: [],

package/src/__tests__/props.test.ts

@@ -0,0 +1,62 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import {toTagDocListProp} from '../props';
+
+describe('toTagDocListProp', () => {
+  type Params = Parameters<typeof toTagDocListProp>[0];
+  type Tag = Params['tag'];
+  type Doc = Params['docs'][number];
+
+  const allTagsPath = '/all/tags';
+
+  test('should work', () => {
+    const tag: Tag = {
+      name: 'tag1',
+      permalink: '/tag1',
+      docIds: ['id1', 'id3'],
+    };
+
+    const doc1: Doc = {
+      id: 'id1',
+      title: 'ZZZ 1',
+      description: 'Description 1',
+      permalink: '/doc1',
+    };
+    const doc2: Doc = {
+      id: 'id2',
+      title: 'XXX 2',
+      description: 'Description 2',
+      permalink: '/doc2',
+    };
+    const doc3: Doc = {
+      id: 'id3',
+      title: 'AAA 3',
+      description: 'Description 3',
+      permalink: '/doc3',
+    };
+    const doc4: Doc = {
+      id: 'id4',
+      title: 'UUU 4',
+      description: 'Description 4',
+      permalink: '/doc4',
+    };
+
+    const result = toTagDocListProp({
+      allTagsPath,
+      tag,
+      docs: [doc1, doc2, doc3, doc4],
+    });
+
+    expect(result).toEqual({
+      allTagsPath,
+      name: tag.name,
+      permalink: tag.permalink,
+      docs: [doc3, doc1], // docs sorted by title, ignore "id5" absence
+    });
+  });
+});