@docusaurus/plugin-content-docs 2.0.0-beta.12faed89d → 2.0.0-beta.13

package/src/{__tests__/__snapshots__/sidebars.test.ts.snap → sidebars/__tests__/__snapshots__/index.test.ts.snap}

@@ -1,10 +1,11 @@
 // Jest Snapshot v1, https://goo.gl/fbAQLP
 
-exports[`loadSidebars sidebars link 1`] = `
+exports[`loadNormalizedSidebars sidebars link 1`] = `
 Object {
   "docs": Array [
     Object {
       "collapsed": true,
+      "collapsible": true,
       "items": Array [
         Object {
           "href": "https://github.com",
@@ -13,20 +14,23 @@ Object {
         },
       ],
       "label": "Test",
+      "link": undefined,
       "type": "category",
     },
   ],
 }
 `;
 
-exports[`loadSidebars sidebars with category.collapsed property 1`] = `
+exports[`loadNormalizedSidebars sidebars with category.collapsed property 1`] = `
 Object {
   "docs": Array [
     Object {
       "collapsed": true,
+      "collapsible": true,
       "items": Array [
         Object {
           "collapsed": false,
+          "collapsible": true,
           "items": Array [
             Object {
               "id": "doc1",
@@ -34,17 +38,21 @@ Object {
             },
           ],
           "label": "Introduction",
+          "link": undefined,
           "type": "category",
         },
       ],
       "label": "Test",
+      "link": undefined,
       "type": "category",
     },
     Object {
       "collapsed": true,
+      "collapsible": true,
       "items": Array [
         Object {
           "collapsed": false,
+          "collapsible": true,
           "items": Array [
             Object {
               "id": "doc2",
@@ -52,21 +60,24 @@ Object {
             },
           ],
           "label": "Powering MDX",
+          "link": undefined,
           "type": "category",
         },
       ],
       "label": "Reference",
+      "link": undefined,
       "type": "category",
     },
   ],
 }
 `;
 
-exports[`loadSidebars sidebars with category.collapsed property at first level 1`] = `
+exports[`loadNormalizedSidebars sidebars with category.collapsed property at first level 1`] = `
 Object {
   "docs": Array [
     Object {
       "collapsed": false,
+      "collapsible": true,
       "items": Array [
         Object {
           "id": "doc1",
@@ -74,10 +85,12 @@ Object {
         },
       ],
       "label": "Introduction",
+      "link": undefined,
       "type": "category",
     },
     Object {
       "collapsed": false,
+      "collapsible": true,
       "items": Array [
         Object {
           "id": "doc2",
@@ -85,17 +98,19 @@ Object {
         },
       ],
       "label": "Powering MDX",
+      "link": undefined,
       "type": "category",
     },
   ],
 }
 `;
 
-exports[`loadSidebars sidebars with deep level of category 1`] = `
+exports[`loadNormalizedSidebars sidebars with deep level of category 1`] = `
 Object {
   "docs": Array [
     Object {
       "collapsed": true,
+      "collapsible": true,
       "items": Array [
         Object {
           "id": "a",
@@ -103,9 +118,11 @@ Object {
         },
         Object {
           "collapsed": true,
+          "collapsible": true,
           "items": Array [
             Object {
               "collapsed": true,
+              "collapsible": true,
               "items": Array [
                 Object {
                   "id": "c",
@@ -113,6 +130,7 @@ Object {
                 },
                 Object {
                   "collapsed": true,
+                  "collapsible": true,
                   "items": Array [
                     Object {
                       "id": "d",
@@ -120,6 +138,7 @@ Object {
                     },
                     Object {
                       "collapsed": true,
+                      "collapsible": true,
                       "items": Array [
                         Object {
                           "id": "e",
@@ -127,14 +146,17 @@ Object {
                         },
                       ],
                       "label": "deeper more more",
+                      "link": undefined,
                       "type": "category",
                     },
                   ],
                   "label": "level 4",
+                  "link": undefined,
                   "type": "category",
                 },
               ],
               "label": "level 3",
+              "link": undefined,
               "type": "category",
             },
             Object {
@@ -143,21 +165,24 @@ Object {
             },
           ],
           "label": "level 2",
+          "link": undefined,
           "type": "category",
         },
       ],
       "label": "level 1",
+      "link": undefined,
       "type": "category",
     },
   ],
 }
 `;
 
-exports[`loadSidebars sidebars with first level not a category 1`] = `
+exports[`loadNormalizedSidebars sidebars with first level not a category 1`] = `
 Object {
   "docs": Array [
     Object {
       "collapsed": true,
+      "collapsible": true,
       "items": Array [
         Object {
           "id": "greeting",
@@ -165,6 +190,7 @@ Object {
         },
       ],
       "label": "Getting Started",
+      "link": undefined,
       "type": "category",
     },
     Object {
@@ -175,11 +201,12 @@ Object {
 }
 `;
 
-exports[`loadSidebars sidebars with known sidebar item type 1`] = `
+exports[`loadNormalizedSidebars sidebars with known sidebar item type 1`] = `
 Object {
   "docs": Array [
     Object {
       "collapsed": true,
+      "collapsible": true,
       "items": Array [
         Object {
           "id": "foo/bar",
@@ -200,10 +227,12 @@ Object {
         },
       ],
       "label": "Test",
+      "link": undefined,
       "type": "category",
     },
     Object {
       "collapsed": true,
+      "collapsible": true,
       "items": Array [
         Object {
           "id": "hello",
@@ -211,6 +240,7 @@ Object {
         },
       ],
       "label": "Guides",
+      "link": undefined,
       "type": "category",
     },
   ],

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