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

package/src/__tests__/__snapshots__/translations.test.ts.snap

@@ -8,6 +8,14 @@ Array [
         "description": "The label for category Getting started in sidebar docs",
         "message": "Getting started",
       },
+      "sidebar.docs.category.Getting started.link.generated-index.description": Object {
+        "description": "The generated-index page description for category Getting started in sidebar docs",
+        "message": "Getting started index description",
+      },
+      "sidebar.docs.category.Getting started.link.generated-index.title": Object {
+        "description": "The generated-index page title for category Getting started in sidebar docs",
+        "message": "Getting started index title",
+      },
       "sidebar.docs.link.Link label": Object {
         "description": "The label for link Link label in sidebar docs, linking to https://facebook.com",
         "message": "Link label",
@@ -25,6 +33,14 @@ Array [
         "description": "The label for category Getting started in sidebar docs",
         "message": "Getting started",
       },
+      "sidebar.docs.category.Getting started.link.generated-index.description": Object {
+        "description": "The generated-index page description for category Getting started in sidebar docs",
+        "message": "Getting started index description",
+      },
+      "sidebar.docs.category.Getting started.link.generated-index.title": Object {
+        "description": "The generated-index page title for category Getting started in sidebar docs",
+        "message": "Getting started index title",
+      },
       "sidebar.docs.link.Link label": Object {
         "description": "The label for link Link label in sidebar docs, linking to https://facebook.com",
         "message": "Link label",
@@ -42,6 +58,14 @@ Array [
         "description": "The label for category Getting started in sidebar docs",
         "message": "Getting started",
       },
+      "sidebar.docs.category.Getting started.link.generated-index.description": Object {
+        "description": "The generated-index page description for category Getting started in sidebar docs",
+        "message": "Getting started index description",
+      },
+      "sidebar.docs.category.Getting started.link.generated-index.title": Object {
+        "description": "The generated-index page title for category Getting started in sidebar docs",
+        "message": "Getting started index title",
+      },
       "sidebar.docs.link.Link label": Object {
         "description": "The label for link Link label in sidebar docs, linking to https://facebook.com",
         "message": "Link label",
@@ -67,7 +91,6 @@ Object {
           "description": "doc1 description",
           "editUrl": "any",
           "id": "doc1",
-          "isDocsHomePage": false,
           "lastUpdatedAt": 0,
           "lastUpdatedBy": "any",
           "next": undefined,
@@ -84,7 +107,6 @@ Object {
           "description": "doc2 description",
           "editUrl": "any",
           "id": "doc2",
-          "isDocsHomePage": false,
           "lastUpdatedAt": 0,
           "lastUpdatedBy": "any",
           "next": undefined,
@@ -101,7 +123,6 @@ Object {
           "description": "doc3 description",
           "editUrl": "any",
           "id": "doc3",
-          "isDocsHomePage": false,
           "lastUpdatedAt": 0,
           "lastUpdatedBy": "any",
           "next": undefined,
@@ -118,7 +139,6 @@ Object {
           "description": "doc4 description",
           "editUrl": "any",
           "id": "doc4",
-          "isDocsHomePage": false,
           "lastUpdatedAt": 0,
           "lastUpdatedBy": "any",
           "next": undefined,
@@ -135,7 +155,6 @@ Object {
           "description": "doc5 description",
           "editUrl": "any",
           "id": "doc5",
-          "isDocsHomePage": false,
           "lastUpdatedAt": 0,
           "lastUpdatedBy": "any",
           "next": undefined,
@@ -151,7 +170,6 @@ Object {
       ],
       "isLast": true,
       "mainDocId": "",
-      "permalinkToSidebar": Object {},
       "routePriority": undefined,
       "sidebarFilePath": "any",
       "sidebars": Object {
@@ -178,6 +196,13 @@ Object {
               },
             ],
             "label": "Getting started (translated)",
+            "link": Object {
+              "description": "Getting started index description (translated)",
+              "permalink": "/docs/category/getting-started-index-slug",
+              "slug": "/category/getting-started-index-slug",
+              "title": "Getting started index title (translated)",
+              "type": "generated-index",
+            },
             "type": "category",
           },
           Object {
@@ -208,7 +233,6 @@ Object {
           "description": "doc1 description",
           "editUrl": "any",
           "id": "doc1",
-          "isDocsHomePage": false,
           "lastUpdatedAt": 0,
           "lastUpdatedBy": "any",
           "next": undefined,
@@ -225,7 +249,6 @@ Object {
           "description": "doc2 description",
           "editUrl": "any",
           "id": "doc2",
-          "isDocsHomePage": false,
           "lastUpdatedAt": 0,
           "lastUpdatedBy": "any",
           "next": undefined,
@@ -242,7 +265,6 @@ Object {
           "description": "doc3 description",
           "editUrl": "any",
           "id": "doc3",
-          "isDocsHomePage": false,
           "lastUpdatedAt": 0,
           "lastUpdatedBy": "any",
           "next": undefined,
@@ -259,7 +281,6 @@ Object {
           "description": "doc4 description",
           "editUrl": "any",
           "id": "doc4",
-          "isDocsHomePage": false,
           "lastUpdatedAt": 0,
           "lastUpdatedBy": "any",
           "next": undefined,
@@ -276,7 +297,6 @@ Object {
           "description": "doc5 description",
           "editUrl": "any",
           "id": "doc5",
-          "isDocsHomePage": false,
           "lastUpdatedAt": 0,
           "lastUpdatedBy": "any",
           "next": undefined,
@@ -292,7 +312,6 @@ Object {
       ],
       "isLast": true,
       "mainDocId": "",
-      "permalinkToSidebar": Object {},
       "routePriority": undefined,
       "sidebarFilePath": "any",
       "sidebars": Object {
@@ -319,6 +338,13 @@ Object {
               },
             ],
             "label": "Getting started (translated)",
+            "link": Object {
+              "description": "Getting started index description (translated)",
+              "permalink": "/docs/category/getting-started-index-slug",
+              "slug": "/category/getting-started-index-slug",
+              "title": "Getting started index title (translated)",
+              "type": "generated-index",
+            },
             "type": "category",
           },
           Object {
@@ -349,7 +375,6 @@ Object {
           "description": "doc1 description",
           "editUrl": "any",
           "id": "doc1",
-          "isDocsHomePage": false,
           "lastUpdatedAt": 0,
           "lastUpdatedBy": "any",
           "next": undefined,
@@ -366,7 +391,6 @@ Object {
           "description": "doc2 description",
           "editUrl": "any",
           "id": "doc2",
-          "isDocsHomePage": false,
           "lastUpdatedAt": 0,
           "lastUpdatedBy": "any",
           "next": undefined,
@@ -383,7 +407,6 @@ Object {
           "description": "doc3 description",
           "editUrl": "any",
           "id": "doc3",
-          "isDocsHomePage": false,
           "lastUpdatedAt": 0,
           "lastUpdatedBy": "any",
           "next": undefined,
@@ -400,7 +423,6 @@ Object {
           "description": "doc4 description",
           "editUrl": "any",
           "id": "doc4",
-          "isDocsHomePage": false,
           "lastUpdatedAt": 0,
           "lastUpdatedBy": "any",
           "next": undefined,
@@ -417,7 +439,6 @@ Object {
           "description": "doc5 description",
           "editUrl": "any",
           "id": "doc5",
-          "isDocsHomePage": false,
           "lastUpdatedAt": 0,
           "lastUpdatedBy": "any",
           "next": undefined,
@@ -433,7 +454,6 @@ Object {
       ],
       "isLast": true,
       "mainDocId": "",
-      "permalinkToSidebar": Object {},
       "routePriority": undefined,
       "sidebarFilePath": "any",
       "sidebars": Object {
@@ -460,6 +480,13 @@ Object {
               },
             ],
             "label": "Getting started (translated)",
+            "link": Object {
+              "description": "Getting started index description (translated)",
+              "permalink": "/docs/category/getting-started-index-slug",
+              "slug": "/category/getting-started-index-slug",
+              "title": "Getting started index title (translated)",
+              "type": "generated-index",
+            },
             "type": "category",
           },
           Object {

package/src/__tests__/cli.test.ts

@@ -7,23 +7,26 @@
 
 import path from 'path';
 import {cliDocsVersionCommand} from '../cli';
-import {PathOptions} from '../types';
+import {PathOptions, SidebarOptions} from '../types';
 import fs from 'fs-extra';
 import {
   getVersionedDocsDirPath,
   getVersionsFilePath,
   getVersionedSidebarsDirPath,
 } from '../versions';
-import {DEFAULT_PLUGIN_ID} from '@docusaurus/core/lib/constants';
+import {DEFAULT_PLUGIN_ID} from '@docusaurus/utils';
 
 const fixtureDir = path.join(__dirname, '__fixtures__');
 
 describe('docsVersion', () => {
   const simpleSiteDir = path.join(fixtureDir, 'simple-site');
   const versionedSiteDir = path.join(fixtureDir, 'versioned-site');
-  const DEFAULT_OPTIONS: PathOptions = {
+
+  const DEFAULT_OPTIONS: PathOptions & SidebarOptions = {
     path: 'docs',
     sidebarPath: '',
+    sidebarCollapsed: true,
+    sidebarCollapsible: true,
   };
 
   test('no version tag provided', () => {
@@ -186,17 +189,17 @@ describe('docsVersion', () => {
     let versionedSidebarPath;
     writeMock.mockImplementationOnce((filepath, content) => {
       versionedSidebarPath = filepath;
-      versionedSidebar = JSON.parse(content);
+      versionedSidebar = JSON.parse(content as string);
     });
     let versionsPath;
     let versions;
     writeMock.mockImplementationOnce((filepath, content) => {
       versionsPath = filepath;
-      versions = JSON.parse(content);
+      versions = JSON.parse(content as string);
     });
     const consoleMock = jest.spyOn(console, 'log').mockImplementation();
     const options = {
-      path: 'docs',
+      ...DEFAULT_OPTIONS,
       sidebarPath: path.join(simpleSiteDir, 'sidebars.json'),
     };
     cliDocsVersionCommand('1.0.0', simpleSiteDir, DEFAULT_PLUGIN_ID, options);
@@ -234,17 +237,17 @@ describe('docsVersion', () => {
     let versionedSidebarPath;
     writeMock.mockImplementationOnce((filepath, content) => {
       versionedSidebarPath = filepath;
-      versionedSidebar = JSON.parse(content);
+      versionedSidebar = JSON.parse(content as string);
     });
     let versionsPath;
     let versions;
     writeMock.mockImplementationOnce((filepath, content) => {
       versionsPath = filepath;
-      versions = JSON.parse(content);
+      versions = JSON.parse(content as string);
     });
     const consoleMock = jest.spyOn(console, 'log').mockImplementation();
     const options = {
-      path: 'docs',
+      ...DEFAULT_OPTIONS,
       sidebarPath: path.join(versionedSiteDir, 'sidebars.json'),
     };
     cliDocsVersionCommand(
@@ -289,16 +292,17 @@ describe('docsVersion', () => {
     let versionedSidebarPath;
     writeMock.mockImplementationOnce((filepath, content) => {
       versionedSidebarPath = filepath;
-      versionedSidebar = JSON.parse(content);
+      versionedSidebar = JSON.parse(content as string);
     });
     let versionsPath;
     let versions;
     writeMock.mockImplementationOnce((filepath, content) => {
       versionsPath = filepath;
-      versions = JSON.parse(content);
+      versions = JSON.parse(content as string);
     });
     const consoleMock = jest.spyOn(console, 'log').mockImplementation();
     const options = {
+      ...DEFAULT_OPTIONS,
       path: 'community',
       sidebarPath: path.join(versionedSiteDir, 'community_sidebars.json'),
     };

package/src/__tests__/docFrontMatter.test.ts

@@ -5,10 +5,12 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import {DocFrontMatter, validateDocFrontMatter} from '../docFrontMatter';
+import {validateDocFrontMatter} from '../docFrontMatter';
+import {DocFrontMatter} from '../types';
+import escapeStringRegexp from 'escape-string-regexp';
 
 function testField(params: {
-  fieldName: keyof DocFrontMatter;
+  prefix: string;
   validFrontMatters: DocFrontMatter[];
   convertibleFrontMatter?: [
     ConvertableFrontMatter: Record<string, unknown>,
@@ -19,27 +21,38 @@ function testField(params: {
     ErrorMessage: string,
   ][];
 }) {
-  describe(`"${params.fieldName}" field`, () => {
-    test('accept valid values', () => {
-      params.validFrontMatters.forEach((frontMatter) => {
-        expect(validateDocFrontMatter(frontMatter)).toEqual(frontMatter);
-      });
+  test(`[${params.prefix}] accept valid values`, () => {
+    params.validFrontMatters.forEach((frontMatter) => {
+      expect(validateDocFrontMatter(frontMatter)).toEqual(frontMatter);
     });
+  });
 
-    test('convert valid values', () => {
-      params.convertibleFrontMatter?.forEach(
-        ([convertibleFrontMatter, convertedFrontMatter]) => {
-          expect(validateDocFrontMatter(convertibleFrontMatter)).toEqual(
-            convertedFrontMatter,
-          );
-        },
-      );
-    });
+  test(`[${params.prefix}] convert valid values`, () => {
+    params.convertibleFrontMatter?.forEach(
+      ([convertibleFrontMatter, convertedFrontMatter]) => {
+        expect(validateDocFrontMatter(convertibleFrontMatter)).toEqual(
+          convertedFrontMatter,
+        );
+      },
+    );
+  });
 
-    test('throw error for values', () => {
-      params.invalidFrontMatters?.forEach(([frontMatter, message]) => {
-        expect(() => validateDocFrontMatter(frontMatter)).toThrow(message);
-      });
+  test(`[${params.prefix}] throw error for values`, () => {
+    params.invalidFrontMatters?.forEach(([frontMatter, message]) => {
+      try {
+        validateDocFrontMatter(frontMatter);
+        fail(
+          new Error(
+            `Doc frontmatter is expected to be rejected, but was accepted successfully:\n ${JSON.stringify(
+              frontMatter,
+              null,
+              2,
+            )}`,
+          ),
+        );
+      } catch (e) {
+        expect(e.message).toMatch(new RegExp(escapeStringRegexp(message)));
+      }
     });
   });
 }
@@ -54,24 +67,30 @@ describe('validateDocFrontMatter', () => {
     const frontMatter = {abc: '1'};
     expect(validateDocFrontMatter(frontMatter)).toEqual(frontMatter);
   });
+});
 
+describe('validateDocFrontMatter id', () => {
   testField({
-    fieldName: 'id',
+    prefix: 'id',
     validFrontMatters: [{id: '123'}, {id: 'unique_id'}],
     invalidFrontMatters: [[{id: ''}, 'is not allowed to be empty']],
   });
+});
 
+describe('validateDocFrontMatter title', () => {
   testField({
-    fieldName: 'title',
+    prefix: 'title',
     validFrontMatters: [
       // See https://github.com/facebook/docusaurus/issues/4591#issuecomment-822372398
       {title: ''},
       {title: 'title'},
     ],
   });
+});
 
+describe('validateDocFrontMatter hide_title', () => {
   testField({
-    fieldName: 'hide_title',
+    prefix: 'hide_title',
     validFrontMatters: [{hide_title: true}, {hide_title: false}],
     convertibleFrontMatter: [
       [{hide_title: 'true'}, {hide_title: true}],
@@ -83,9 +102,11 @@ describe('validateDocFrontMatter', () => {
       [{hide_title: ''}, 'must be a boolean'],
     ],
   });
+});
 
+describe('validateDocFrontMatter hide_table_of_contents', () => {
   testField({
-    fieldName: 'hide_table_of_contents',
+    prefix: 'hide_table_of_contents',
     validFrontMatters: [
       {hide_table_of_contents: true},
       {hide_table_of_contents: false},
@@ -100,9 +121,11 @@ describe('validateDocFrontMatter', () => {
       [{hide_table_of_contents: ''}, 'must be a boolean'],
     ],
   });
+});
 
+describe('validateDocFrontMatter keywords', () => {
   testField({
-    fieldName: 'keywords',
+    prefix: 'keywords',
     validFrontMatters: [
       {keywords: ['hello']},
       {keywords: ['hello', 'world']},
@@ -115,29 +138,36 @@ describe('validateDocFrontMatter', () => {
       [{keywords: []}, 'does not contain 1 required value(s)'],
     ],
   });
+});
 
+describe('validateDocFrontMatter image', () => {
   testField({
-    fieldName: 'image',
-    validFrontMatters: [{image: 'https://docusaurus.io/blog/image.png'}],
+    prefix: 'image',
+    validFrontMatters: [
+      {image: 'https://docusaurus.io/blog/image.png'},
+      {image: '/absolute/image.png'},
+      {image: '../relative/image.png'},
+    ],
     invalidFrontMatters: [
-      [{image: ''}, 'is not allowed to be empty'],
-      [{image: './api/@docusaurus/plugin-debug'}, 'must be a valid uri'],
-      [{image: '/api/@docusaurus/plugin-debug'}, 'must be a valid uri'],
-      [{image: '@site/api/asset/image.png'}, 'must be a valid uri'],
+      [{image: ''}, '"image" does not look like a valid url (value=\'\')'],
     ],
   });
+});
 
+describe('validateDocFrontMatter description', () => {
   testField({
-    fieldName: 'description',
+    prefix: 'description',
     validFrontMatters: [
       // See https://github.com/facebook/docusaurus/issues/4591#issuecomment-822372398
       {description: ''},
       {description: 'description'},
     ],
   });
+});
 
+describe('validateDocFrontMatter slug', () => {
   testField({
-    fieldName: 'slug',
+    prefix: 'slug',
     validFrontMatters: [
       {slug: '/'},
       {slug: 'slug'},
@@ -150,31 +180,37 @@ describe('validateDocFrontMatter', () => {
     ],
     invalidFrontMatters: [[{slug: ''}, 'is not allowed to be empty']],
   });
+});
 
+describe('validateDocFrontMatter sidebar_label', () => {
   testField({
-    fieldName: 'sidebar_label',
+    prefix: 'sidebar_label',
     validFrontMatters: [{sidebar_label: 'Awesome docs'}],
     invalidFrontMatters: [[{sidebar_label: ''}, 'is not allowed to be empty']],
   });
+});
 
+describe('validateDocFrontMatter sidebar_position', () => {
   testField({
-    fieldName: 'sidebar_position',
+    prefix: 'sidebar_position',
     validFrontMatters: [
+      {sidebar_position: -5},
+      {sidebar_position: -3.5},
       {sidebar_position: 0},
       {sidebar_position: 5},
       {sidebar_position: 3.5},
     ],
     convertibleFrontMatter: [
+      [{sidebar_position: '-1.5'}, {sidebar_position: -1.5}],
       [{sidebar_position: '1'}, {sidebar_position: 1}],
       [{sidebar_position: '1.5'}, {sidebar_position: 1.5}],
     ],
-    invalidFrontMatters: [
-      [{sidebar_position: -1}, 'must be greater than or equal to 0'],
-    ],
   });
+});
 
+describe('validateDocFrontMatter custom_edit_url', () => {
   testField({
-    fieldName: 'custom_edit_url',
+    prefix: 'custom_edit_url',
     validFrontMatters: [
       // See https://github.com/demisto/content-docs/pull/616#issuecomment-827087566
       {custom_edit_url: ''},
@@ -184,9 +220,11 @@ describe('validateDocFrontMatter', () => {
       {custom_edit_url: '@site/api/docs/markdown.md'},
     ],
   });
+});
 
+describe('validateDocFrontMatter parse_number_prefixes', () => {
   testField({
-    fieldName: 'parse_number_prefixes',
+    prefix: 'parse_number_prefixes',
     validFrontMatters: [
       {parse_number_prefixes: true},
       {parse_number_prefixes: false},
@@ -202,3 +240,120 @@ describe('validateDocFrontMatter', () => {
     ],
   });
 });
+
+describe('validateDocFrontMatter tags', () => {
+  testField({
+    prefix: 'tags',
+    validFrontMatters: [{}, {tags: undefined}, {tags: ['tag1', 'tag2']}],
+    convertibleFrontMatter: [[{tags: ['tag1', 42]}, {tags: ['tag1', '42']}]],
+    invalidFrontMatters: [
+      [{tags: 42}, '"tags" does not look like a valid FrontMatter Yaml array.'],
+      [
+        {tags: 'tag1, tag2'},
+        '"tags" does not look like a valid FrontMatter Yaml array.',
+      ],
+      [{tags: [{}]}, '"tags[0]" does not look like a valid tag'],
+      [{tags: [true]}, '"tags[0]" does not look like a valid tag'],
+      [
+        {tags: ['tag1', {hey: 'test'}]},
+        '"tags[1]" does not look like a valid tag',
+      ],
+    ],
+  });
+});
+
+describe('validateDocFrontMatter toc_min_heading_level', () => {
+  testField({
+    prefix: 'toc_min_heading_level',
+    validFrontMatters: [
+      {},
+      {toc_min_heading_level: undefined},
+      {toc_min_heading_level: 2},
+      {toc_min_heading_level: 3},
+      {toc_min_heading_level: 4},
+      {toc_min_heading_level: 5},
+      {toc_min_heading_level: 6},
+    ],
+    convertibleFrontMatter: [
+      [{toc_min_heading_level: '2'}, {toc_min_heading_level: 2}],
+    ],
+    invalidFrontMatters: [
+      [
+        {toc_min_heading_level: 1},
+        '"toc_min_heading_level" must be greater than or equal to 2',
+      ],
+      [
+        {toc_min_heading_level: 7},
+        '"toc_min_heading_level" must be less than or equal to 6',
+      ],
+      [
+        {toc_min_heading_level: 'hello'},
+        '"toc_min_heading_level" must be a number',
+      ],
+      [
+        {toc_min_heading_level: true},
+        '"toc_min_heading_level" must be a number',
+      ],
+    ],
+  });
+});
+
+describe('validateDocFrontMatter toc_max_heading_level', () => {
+  testField({
+    prefix: 'toc_max_heading_level',
+    validFrontMatters: [
+      {},
+      {toc_max_heading_level: undefined},
+      {toc_max_heading_level: 2},
+      {toc_max_heading_level: 3},
+      {toc_max_heading_level: 4},
+      {toc_max_heading_level: 5},
+      {toc_max_heading_level: 6},
+    ],
+    convertibleFrontMatter: [
+      [{toc_max_heading_level: '2'}, {toc_max_heading_level: 2}],
+    ],
+    invalidFrontMatters: [
+      [
+        {toc_max_heading_level: 1},
+        '"toc_max_heading_level" must be greater than or equal to 2',
+      ],
+      [
+        {toc_max_heading_level: 7},
+        '"toc_max_heading_level" must be less than or equal to 6',
+      ],
+      [
+        {toc_max_heading_level: 'hello'},
+        '"toc_max_heading_level" must be a number',
+      ],
+      [
+        {toc_max_heading_level: true},
+        '"toc_max_heading_level" must be a number',
+      ],
+    ],
+  });
+});
+
+describe('validateDocFrontMatter toc min/max consistency', () => {
+  testField({
+    prefix: 'toc min/max',
+    validFrontMatters: [
+      {},
+      {toc_min_heading_level: undefined, toc_max_heading_level: undefined},
+      {toc_min_heading_level: 2, toc_max_heading_level: 2},
+      {toc_min_heading_level: 2, toc_max_heading_level: 6},
+      {toc_min_heading_level: 2, toc_max_heading_level: 3},
+      {toc_min_heading_level: 3, toc_max_heading_level: 3},
+    ],
+    invalidFrontMatters: [
+      [
+        {toc_min_heading_level: 4, toc_max_heading_level: 3},
+        '"toc_min_heading_level" must be less than or equal to ref:toc_max_heading_level',
+      ],
+      [
+        {toc_min_heading_level: 6, toc_max_heading_level: 2},
+        '"toc_min_heading_level" must be less than or equal to ref:toc_max_heading_level',
+      ],
+    ],
+  });
+});