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

package/src/{__tests__/sidebarItemsGenerator.test.ts → sidebars/__tests__/generator.test.ts}

@@ -5,18 +5,14 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import {
-  CategoryMetadatasFile,
-  DefaultSidebarItemsGenerator,
-} from '../sidebarItemsGenerator';
-import {DefaultCategoryCollapsedValue} from '../sidebars';
+import {CategoryMetadataFile, DefaultSidebarItemsGenerator} from '../generator';
 import {Sidebar, SidebarItemsGenerator} from '../types';
 import fs from 'fs-extra';
-import {DefaultNumberPrefixParser} from '../numberPrefix';
+import {DefaultNumberPrefixParser} from '../../numberPrefix';
 
 describe('DefaultSidebarItemsGenerator', () => {
   function testDefaultSidebarItemsGenerator(
-    options: Partial<Parameters<SidebarItemsGenerator>[0]>,
+    params: Partial<Parameters<SidebarItemsGenerator>[0]>,
   ) {
     return DefaultSidebarItemsGenerator({
       numberPrefixParser: DefaultNumberPrefixParser,
@@ -29,21 +25,27 @@ describe('DefaultSidebarItemsGenerator', () => {
         contentPath: 'docs',
       },
       docs: [],
-      ...options,
+      options: {
+        sidebarCollapsed: true,
+        sidebarCollapsible: true,
+      },
+      ...params,
     });
   }
 
   function mockCategoryMetadataFiles(
-    categoryMetadataFiles: Record<string, Partial<CategoryMetadatasFile>>,
+    categoryMetadataFiles: Record<string, Partial<CategoryMetadataFile>>,
   ) {
-    jest.spyOn(fs, 'pathExists').mockImplementation((metadataFilePath) => {
-      return typeof categoryMetadataFiles[metadataFilePath] !== 'undefined';
-    });
+    jest
+      .spyOn(fs, 'pathExists')
+      .mockImplementation(
+        (metadataFilePath) =>
+          typeof categoryMetadataFiles[metadataFilePath] !== 'undefined',
+      );
     jest.spyOn(fs, 'readFile').mockImplementation(
       // @ts-expect-error: annoying TS error due to overrides
-      async (metadataFilePath: string) => {
-        return JSON.stringify(categoryMetadataFiles[metadataFilePath]);
-      },
+      async (metadataFilePath: string) =>
+        JSON.stringify(categoryMetadataFiles[metadataFilePath]),
     );
   }
 
@@ -110,6 +112,10 @@ describe('DefaultSidebarItemsGenerator', () => {
           frontMatter: {},
         },
       ],
+      options: {
+        sidebarCollapsed: true,
+        sidebarCollapsible: true,
+      },
     });
 
     expect(sidebarSlice).toEqual([
@@ -123,9 +129,15 @@ describe('DefaultSidebarItemsGenerator', () => {
 
   test('generates complex nested sidebar', async () => {
     mockCategoryMetadataFiles({
-      '02-Guides/_category_.json': {collapsed: false},
+      '02-Guides/_category_.json': {collapsed: false} as CategoryMetadataFile,
       '02-Guides/01-SubGuides/_category_.yml': {
         label: 'SubGuides (metadata file label)',
+        link: {
+          type: 'generated-index',
+          slug: 'subguides-generated-index-slug',
+          title: 'subguides-title',
+          description: 'subguides-description',
+        },
       },
     });
 
@@ -147,6 +159,13 @@ describe('DefaultSidebarItemsGenerator', () => {
           sidebarPosition: 1,
           frontMatter: {},
         },
+        {
+          id: 'tutorials-index',
+          source: 'index.md',
+          sourceDirName: '01-Tutorials',
+          sidebarPosition: 2,
+          frontMatter: {},
+        },
         {
           id: 'tutorial2',
           source: 'tutorial2.md',
@@ -161,6 +180,12 @@ describe('DefaultSidebarItemsGenerator', () => {
           sidebarPosition: 1,
           frontMatter: {},
         },
+        {
+          id: 'guides-index',
+          source: '02-Guides.md', // TODO should we allow to just use "Guides.md" to have an index?
+          sourceDirName: '02-Guides',
+          frontMatter: {},
+        },
         {
           id: 'guide2',
           source: 'guide2.md',
@@ -190,6 +215,10 @@ describe('DefaultSidebarItemsGenerator', () => {
           frontMatter: {},
         },
       ],
+      options: {
+        sidebarCollapsed: true,
+        sidebarCollapsible: true,
+      },
     });
 
     expect(sidebarSlice).toEqual([
@@ -197,7 +226,12 @@ describe('DefaultSidebarItemsGenerator', () => {
       {
         type: 'category',
         label: 'Tutorials',
-        collapsed: DefaultCategoryCollapsedValue,
+        collapsed: true,
+        collapsible: true,
+        link: {
+          type: 'doc',
+          id: 'tutorials-index',
+        },
         items: [
           {type: 'doc', id: 'tutorial1'},
           {type: 'doc', id: 'tutorial2'},
@@ -207,13 +241,25 @@ describe('DefaultSidebarItemsGenerator', () => {
         type: 'category',
         label: 'Guides',
         collapsed: false,
+        collapsible: true,
+        link: {
+          type: 'doc',
+          id: 'guides-index',
+        },
         items: [
           {type: 'doc', id: 'guide1'},
           {
             type: 'category',
             label: 'SubGuides (metadata file label)',
-            collapsed: DefaultCategoryCollapsedValue,
+            collapsed: true,
+            collapsible: true,
             items: [{type: 'doc', id: 'nested-guide'}],
+            link: {
+              type: 'generated-index',
+              slug: 'subguides-generated-index-slug',
+              title: 'subguides-title',
+              description: 'subguides-description',
+            },
           },
           {type: 'doc', id: 'guide2'},
         ],
@@ -233,6 +279,7 @@ describe('DefaultSidebarItemsGenerator', () => {
       'subfolder/subsubfolder/subsubsubfolder3/_category_.json': {
         position: 1,
         label: 'subsubsubfolder3 (_category_.json label)',
+        collapsible: false,
         collapsed: false,
       },
     });
@@ -305,6 +352,10 @@ describe('DefaultSidebarItemsGenerator', () => {
           frontMatter: {},
         },
       ],
+      options: {
+        sidebarCollapsed: true,
+        sidebarCollapsible: true,
+      },
     });
 
     expect(sidebarSlice).toEqual([
@@ -312,6 +363,7 @@ describe('DefaultSidebarItemsGenerator', () => {
         type: 'category',
         label: 'subsubsubfolder3 (_category_.json label)',
         collapsed: false,
+        collapsible: false,
         items: [
           {type: 'doc', id: 'doc8'},
           {type: 'doc', id: 'doc7'},
@@ -321,6 +373,7 @@ describe('DefaultSidebarItemsGenerator', () => {
         type: 'category',
         label: 'subsubsubfolder2 (_category_.yml label)',
         collapsed: true,
+        collapsible: true,
         items: [{type: 'doc', id: 'doc6'}],
       },
       {type: 'doc', id: 'doc1'},
@@ -329,8 +382,80 @@ describe('DefaultSidebarItemsGenerator', () => {
         type: 'category',
         label: 'subsubsubfolder',
         collapsed: true,
+        collapsible: true,
         items: [{type: 'doc', id: 'doc5'}],
       },
     ] as Sidebar);
   });
+
+  test('uses explicit link over the index/readme.{md,mdx} naming convention', async () => {
+    mockCategoryMetadataFiles({
+      'Category/_category_.yml': {
+        label: 'Category label',
+        link: {
+          type: 'doc',
+          id: 'doc3', // Using a "local doc id" ("doc1" instead of "parent/doc1") on purpose
+        },
+      },
+    });
+
+    const sidebarSlice = await DefaultSidebarItemsGenerator({
+      numberPrefixParser: DefaultNumberPrefixParser,
+      item: {
+        type: 'autogenerated',
+        dirName: '.',
+      },
+      version: {
+        versionName: 'current',
+        contentPath: '',
+      },
+      docs: [
+        {
+          id: 'parent/doc1',
+          source: 'index.md',
+          sourceDirName: 'Category',
+          frontMatter: {},
+        },
+        {
+          id: 'parent/doc2',
+          source: 'index.md',
+          sourceDirName: 'Category',
+          frontMatter: {},
+        },
+        {
+          id: 'parent/doc3',
+          source: 'doc3.md',
+          sourceDirName: 'Category',
+          frontMatter: {},
+        },
+      ],
+      options: {
+        sidebarCollapsed: true,
+        sidebarCollapsible: true,
+      },
+    });
+
+    expect(sidebarSlice).toEqual([
+      {
+        type: 'category',
+        label: 'Category label',
+        collapsed: true,
+        collapsible: true,
+        link: {
+          id: 'parent/doc3',
+          type: 'doc',
+        },
+        items: [
+          {
+            id: 'parent/doc1',
+            type: 'doc',
+          },
+          {
+            id: 'parent/doc2',
+            type: 'doc',
+          },
+        ],
+      },
+    ] as Sidebar);
+  });
 });

package/src/sidebars/__tests__/index.test.ts

@@ -0,0 +1,204 @@
+/**
+ * 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 path from 'path';
+import {
+  loadNormalizedSidebars,
+  DefaultSidebars,
+  DisabledSidebars,
+} from '../index';
+import type {NormalizeSidebarsParams, VersionMetadata} from '../../types';
+
+describe('loadNormalizedSidebars', () => {
+  const fixtureDir = path.join(__dirname, '__fixtures__', 'sidebars');
+  const options: NormalizeSidebarsParams = {
+    sidebarCollapsed: true,
+    sidebarCollapsible: true,
+    version: {
+      versionName: 'version',
+      versionPath: 'versionPath',
+    } as VersionMetadata,
+  };
+  test('sidebars with known sidebar item type', async () => {
+    const sidebarPath = path.join(fixtureDir, 'sidebars.json');
+    const result = loadNormalizedSidebars(sidebarPath, options);
+    expect(result).toMatchSnapshot();
+  });
+
+  test('sidebars with deep level of category', async () => {
+    const sidebarPath = path.join(fixtureDir, 'sidebars-category.js');
+    const result = loadNormalizedSidebars(sidebarPath, options);
+    expect(result).toMatchSnapshot();
+  });
+
+  test('sidebars shorthand and longform lead to exact same sidebar', async () => {
+    const sidebarPath1 = path.join(fixtureDir, 'sidebars-category.js');
+    const sidebarPath2 = path.join(
+      fixtureDir,
+      'sidebars-category-shorthand.js',
+    );
+    const sidebar1 = loadNormalizedSidebars(sidebarPath1, options);
+    const sidebar2 = loadNormalizedSidebars(sidebarPath2, options);
+    expect(sidebar1).toEqual(sidebar2);
+  });
+
+  test('sidebars with category but category.items is not an array', async () => {
+    const sidebarPath = path.join(
+      fixtureDir,
+      'sidebars-category-wrong-items.json',
+    );
+    expect(() => loadNormalizedSidebars(sidebarPath, options))
+      .toThrowErrorMatchingInlineSnapshot(`
+      "{
+        \\"type\\": \\"category\\",
+        \\"label\\": \\"Category Label\\",
+        \\"items\\" [1]: \\"doc1\\"
+      }
+      
+      [1] \\"items\\" must be an array"
+    `);
+  });
+
+  test('sidebars with category but category label is not a string', async () => {
+    const sidebarPath = path.join(
+      fixtureDir,
+      'sidebars-category-wrong-label.json',
+    );
+    expect(() => loadNormalizedSidebars(sidebarPath, options))
+      .toThrowErrorMatchingInlineSnapshot(`
+      "{
+        \\"type\\": \\"category\\",
+        \\"items\\": [
+          \\"doc1\\"
+        ],
+        \\"label\\" [1]: true
+      }
+      
+      [1] \\"label\\" must be a string"
+    `);
+  });
+
+  test('sidebars item doc but id is not a string', async () => {
+    const sidebarPath = path.join(
+      fixtureDir,
+      'sidebars-doc-id-not-string.json',
+    );
+    expect(() => loadNormalizedSidebars(sidebarPath, options))
+      .toThrowErrorMatchingInlineSnapshot(`
+      "{
+        \\"type\\": \\"doc\\",
+        \\"id\\" [1]: [
+          \\"doc1\\"
+        ]
+      }
+      
+      [1] \\"id\\" must be a string"
+    `);
+  });
+
+  test('sidebars with first level not a category', async () => {
+    const sidebarPath = path.join(
+      fixtureDir,
+      'sidebars-first-level-not-category.js',
+    );
+    const result = loadNormalizedSidebars(sidebarPath, options);
+    expect(result).toMatchSnapshot();
+  });
+
+  test('sidebars link', async () => {
+    const sidebarPath = path.join(fixtureDir, 'sidebars-link.json');
+    const result = loadNormalizedSidebars(sidebarPath, options);
+    expect(result).toMatchSnapshot();
+  });
+
+  test('sidebars link wrong label', async () => {
+    const sidebarPath = path.join(fixtureDir, 'sidebars-link-wrong-label.json');
+    expect(() => loadNormalizedSidebars(sidebarPath, options))
+      .toThrowErrorMatchingInlineSnapshot(`
+      "{
+        \\"type\\": \\"link\\",
+        \\"href\\": \\"https://github.com\\",
+        \\"label\\" [1]: false
+      }
+      
+      [1] \\"label\\" must be a string"
+    `);
+  });
+
+  test('sidebars link wrong href', async () => {
+    const sidebarPath = path.join(fixtureDir, 'sidebars-link-wrong-href.json');
+    expect(() => loadNormalizedSidebars(sidebarPath, options))
+      .toThrowErrorMatchingInlineSnapshot(`
+      "{
+        \\"type\\": \\"link\\",
+        \\"label\\": \\"GitHub\\",
+        \\"href\\" [1]: [
+          \\"example.com\\"
+        ]
+      }
+      
+      [1] \\"href\\" contains an invalid value"
+    `);
+  });
+
+  test('sidebars with unknown sidebar item type', async () => {
+    const sidebarPath = path.join(fixtureDir, 'sidebars-unknown-type.json');
+    expect(() => loadNormalizedSidebars(sidebarPath, options))
+      .toThrowErrorMatchingInlineSnapshot(`
+      "{
+        \\"type\\": \\"superman\\",
+        \\"undefined\\" [1]: -- missing --
+      }
+      
+      [1] Unknown sidebar item type \\"superman\\"."
+    `);
+  });
+
+  test('sidebars with known sidebar item type but wrong field', async () => {
+    const sidebarPath = path.join(fixtureDir, 'sidebars-wrong-field.json');
+    expect(() => loadNormalizedSidebars(sidebarPath, options))
+      .toThrowErrorMatchingInlineSnapshot(`
+      "{
+        \\"type\\": \\"category\\",
+        \\"label\\": \\"category\\",
+        \\"href\\": \\"https://github.com\\",
+        \\"items\\" [1]: -- missing --
+      }
+      
+      [1] \\"items\\" is required"
+    `);
+  });
+
+  test('unexisting path', () => {
+    expect(loadNormalizedSidebars('badpath', options)).toEqual(
+      DisabledSidebars,
+    );
+  });
+
+  test('undefined path', () => {
+    expect(loadNormalizedSidebars(undefined, options)).toEqual(DefaultSidebars);
+  });
+
+  test('literal false path', () => {
+    expect(loadNormalizedSidebars(false, options)).toEqual(DisabledSidebars);
+  });
+
+  test('sidebars with category.collapsed property', async () => {
+    const sidebarPath = path.join(fixtureDir, 'sidebars-collapsed.json');
+    const result = loadNormalizedSidebars(sidebarPath, options);
+    expect(result).toMatchSnapshot();
+  });
+
+  test('sidebars with category.collapsed property at first level', async () => {
+    const sidebarPath = path.join(
+      fixtureDir,
+      'sidebars-collapsed-first-level.json',
+    );
+    const result = loadNormalizedSidebars(sidebarPath, options);
+    expect(result).toMatchSnapshot();
+  });
+});