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

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) => {
@@ -105,9 +103,6 @@ Entries created:
         `version-${kebabCase(version.versionName)}-metadata-prop`,
       );
       expect(versionMetadataProp.docsSidebars).toEqual(toSidebarsProp(version));
-      expect(versionMetadataProp.permalinkToSidebar).toEqual(
-        version.permalinkToSidebar,
-      );
     },
 
     expectSnapshot: () => {
@@ -273,6 +268,8 @@ describe('simple website', () => {
     expect(mock).toHaveBeenCalledWith('1.0.0', siteDir, DEFAULT_PLUGIN_ID, {
       path: 'docs',
       sidebarPath,
+      sidebarCollapsed: true,
+      sidebarCollapsible: true,
     });
     mock.mockRestore();
   });
@@ -309,6 +306,8 @@ describe('simple website', () => {
   test('configureWebpack', async () => {
     const {plugin} = await loadSite();
 
+    const content = await plugin.loadContent?.();
+
     const config = applyConfigureWebpack(
       plugin.configureWebpack,
       {
@@ -319,6 +318,8 @@ describe('simple website', () => {
         },
       },
       false,
+      undefined,
+      content,
     );
     const errors = validate(config);
     expect(errors).toBeUndefined();
@@ -344,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)),
@@ -361,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({
@@ -374,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(
@@ -389,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({
@@ -477,6 +506,8 @@ describe('versioned website', () => {
     expect(mock).toHaveBeenCalledWith('2.0.0', siteDir, DEFAULT_PLUGIN_ID, {
       path: routeBasePath,
       sidebarPath,
+      sidebarCollapsed: true,
+      sidebarCollapsible: true,
     });
     mock.mockRestore();
   });
@@ -544,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();
@@ -574,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',
@@ -581,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,
@@ -710,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();
@@ -728,6 +760,8 @@ describe('versioned website (community)', () => {
     expect(mock).toHaveBeenCalledWith('2.0.0', siteDir, pluginId, {
       path: routeBasePath,
       sidebarPath,
+      sidebarCollapsed: true,
+      sidebarCollapsible: true,
     });
     mock.mockRestore();
   });
@@ -906,6 +940,7 @@ describe('site with full autogenerated sidebar', () => {
           type: 'category',
           label: 'Guides',
           collapsed: true,
+          collapsible: true,
           items: [
             {
               type: 'doc',
@@ -937,6 +972,7 @@ describe('site with full autogenerated sidebar', () => {
           type: 'category',
           label: 'API (label from _category_.json)',
           collapsed: true,
+          collapsible: true,
           items: [
             {
               type: 'doc',
@@ -946,6 +982,7 @@ describe('site with full autogenerated sidebar', () => {
               type: 'category',
               label: 'Core APIs',
               collapsed: true,
+              collapsible: true,
               items: [
                 {
                   type: 'doc',
@@ -962,6 +999,7 @@ describe('site with full autogenerated sidebar', () => {
               type: 'category',
               label: 'Extension APIs (label from _category_.yml)',
               collapsed: true,
+              collapsible: true,
               items: [
                 {
                   type: 'doc',
@@ -1460,6 +1498,7 @@ describe('site with partial autogenerated sidebars', () => {
           type: 'category',
           label: 'Some category',
           collapsed: true,
+          collapsible: true,
           items: [
             {
               type: 'doc',
@@ -1649,6 +1688,7 @@ describe('site with partial autogenerated sidebars 2 (fix #4638)', () => {
           type: 'category',
           label: 'Core APIs',
           collapsed: true,
+          collapsible: true,
           items: [
             {
               type: 'doc',
@@ -1665,6 +1705,7 @@ describe('site with partial autogenerated sidebars 2 (fix #4638)', () => {
           type: 'category',
           label: 'Extension APIs (label from _category_.yml)', // Fix #4638
           collapsed: true,
+          collapsible: true,
           items: [
             {
               type: 'doc',
@@ -1734,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];
@@ -1781,6 +1821,7 @@ describe('site with custom sidebar items generator', () => {
           type: 'category',
           label: 'API (label from _category_.json)',
           collapsed: true,
+          collapsible: true,
           items: [
             {
               type: 'doc',
@@ -1790,6 +1831,7 @@ describe('site with custom sidebar items generator', () => {
               type: 'category',
               label: 'Extension APIs (label from _category_.yml)',
               collapsed: true,
+              collapsible: true,
               items: [
                 {
                   type: 'doc',
@@ -1805,6 +1847,7 @@ describe('site with custom sidebar items generator', () => {
               type: 'category',
               label: 'Core APIs',
               collapsed: true,
+              collapsible: true,
               items: [
                 {
                   type: 'doc',
@@ -1826,6 +1869,7 @@ describe('site with custom sidebar items generator', () => {
           type: 'category',
           label: 'Guides',
           collapsed: true,
+          collapsible: true,
           items: [
             {
               type: 'doc',

package/src/__tests__/lastUpdate.test.ts

@@ -31,15 +31,16 @@ describe('lastUpdate', () => {
   test('non-existing file', async () => {
     const consoleMock = jest.spyOn(console, 'error');
     consoleMock.mockImplementation();
+    const nonExistingFileName = '.nonExisting';
     const nonExistingFilePath = path.join(
       __dirname,
       '__fixtures__',
-      '.nonExisting',
+      nonExistingFileName,
     );
     expect(await getFileLastUpdate(nonExistingFilePath)).toBeNull();
     expect(consoleMock).toHaveBeenCalledTimes(1);
     expect(consoleMock.mock.calls[0][0].message).toContain(
-      `Command failed with exit code 128: git log -1 --format=%ct, %an ${nonExistingFilePath}`,
+      `Command failed with exit code 128: git log -1 --format=%ct, %an ${nonExistingFileName}`,
     );
     expect(await getFileLastUpdate(null)).toBeNull();
     expect(await getFileLastUpdate(undefined)).toBeNull();

package/src/__tests__/options.test.ts

@@ -5,18 +5,30 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import {OptionsSchema, DEFAULT_OPTIONS} from '../options';
+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,
 } from '../numberPrefix';
+import {GlobExcludeDefault} from '@docusaurus/utils';
+import {PluginOptions} from '../types';
 
 // the type of remark/rehype plugins is function
 const markdownPluginsFunctionStub = () => {};
 const markdownPluginsObjectStub = {};
 
+function testValidateOptions(options: Partial<PluginOptions>) {
+  return validateOptions({
+    options: {
+      ...DEFAULT_OPTIONS,
+      ...options,
+    },
+    validate: normalizePluginOptions,
+  });
+}
+
 describe('normalizeDocsPluginOptions', () => {
   test('should return default options for undefined user options', async () => {
     const {value, error} = await OptionsSchema.validate({});
@@ -28,13 +40,17 @@ 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,
       sidebarPath: 'my-sidebar', // Path to sidebar configuration for showing a list of markdown pages.
       sidebarItemsGenerator: DefaultSidebarItemsGenerator,
       numberPrefixParser: DefaultNumberPrefixParser,
       docLayoutComponent: '@theme/DocPage',
       docItemComponent: '@theme/DocItem',
+      docTagDocListComponent: '@theme/DocTagDocListPage',
+      docTagsListComponent: '@theme/DocTagsListPage',
       remarkPlugins: [markdownPluginsObjectStub],
       rehypePlugins: [markdownPluginsFunctionStub],
       beforeDefaultRehypePlugins: [],
@@ -42,7 +58,6 @@ describe('normalizeDocsPluginOptions', () => {
       showLastUpdateTime: true,
       showLastUpdateAuthor: true,
       admonitions: {},
-      excludeNextVersionDocs: true,
       includeCurrentVersion: false,
       disableVersioning: true,
       editCurrentVersion: true,
@@ -57,6 +72,8 @@ describe('normalizeDocsPluginOptions', () => {
           label: 'world',
         },
       },
+      sidebarCollapsible: false,
+      sidebarCollapsed: false,
     };
     const {value, error} = await OptionsSchema.validate(userOptions);
     expect(value).toEqual(userOptions);
@@ -229,4 +246,30 @@ describe('normalizeDocsPluginOptions', () => {
       `"\\"versions.current.hey\\" is not allowed"`,
     );
   });
+
+  test('should handle sidebarCollapsed option inconsistencies', () => {
+    expect(
+      testValidateOptions({
+        ...DEFAULT_OPTIONS,
+        sidebarCollapsible: true,
+        sidebarCollapsed: undefined,
+      }).sidebarCollapsed,
+    ).toEqual(true);
+
+    expect(
+      testValidateOptions({
+        ...DEFAULT_OPTIONS,
+        sidebarCollapsible: false,
+        sidebarCollapsed: undefined,
+      }).sidebarCollapsed,
+    ).toEqual(false);
+
+    expect(
+      testValidateOptions({
+        ...DEFAULT_OPTIONS,
+        sidebarCollapsible: false,
+        sidebarCollapsed: true,
+      }).sidebarCollapsed,
+    ).toEqual(false);
+  });
 });

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
+    });
+  });
+});

package/src/__tests__/translations.test.ts

@@ -40,7 +40,6 @@ function createSampleVersion(
     versionLabel: `${version.versionName} label`,
     versionPath: '/docs/',
     mainDocId: '',
-    permalinkToSidebar: {},
     routePriority: undefined,
     sidebarFilePath: 'any',
     isLast: true,