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

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,18 @@ describe('normalizeDocsPluginOptions', () => {
     const userOptions = {
       path: 'my-docs', // Path to data on filesystem, relative to site dir.
       routeBasePath: 'my-docs', // URL Route.
-      homePageId: 'home', // Document id for docs home page.
+      tagsBasePath: 'tags', // URL Tags Route.
       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',
+      docCategoryGeneratedIndexComponent:
+        '@theme/DocCategoryGeneratedIndexPage',
       remarkPlugins: [markdownPluginsObjectStub],
       rehypePlugins: [markdownPluginsFunctionStub],
       beforeDefaultRehypePlugins: [],
@@ -42,7 +59,6 @@ describe('normalizeDocsPluginOptions', () => {
       showLastUpdateTime: true,
       showLastUpdateAuthor: true,
       admonitions: {},
-      excludeNextVersionDocs: true,
       includeCurrentVersion: false,
       disableVersioning: true,
       editCurrentVersion: true,
@@ -57,6 +73,8 @@ describe('normalizeDocsPluginOptions', () => {
           label: 'world',
         },
       },
+      sidebarCollapsible: false,
+      sidebarCollapsed: false,
     };
     const {value, error} = await OptionsSchema.validate(userOptions);
     expect(value).toEqual(userOptions);
@@ -229,4 +247,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__/slug.test.ts

@@ -9,24 +9,92 @@ import getSlug from '../slug';
 
 describe('getSlug', () => {
   test('should default to dirname/id', () => {
-    expect(getSlug({baseID: 'doc', dirName: '/dir'})).toEqual('/dir/doc');
-    expect(getSlug({baseID: 'doc', dirName: '/dir/subdir'})).toEqual(
-      '/dir/subdir/doc',
-    );
+    expect(
+      getSlug({
+        baseID: 'doc',
+        source: '@site/docs/dir/doc.md',
+        sourceDirName: '/dir',
+      }),
+    ).toEqual('/dir/doc');
+    expect(
+      getSlug({
+        baseID: 'doc',
+        source: '@site/docs/dir/subdir/doc.md',
+        sourceDirName: '/dir/subdir',
+      }),
+    ).toEqual('/dir/subdir/doc');
+  });
+
+  test('should handle conventional doc indexes', () => {
+    expect(
+      getSlug({
+        baseID: 'doc',
+        source: '@site/docs/dir/subdir/index.md',
+        sourceDirName: '/dir/subdir',
+      }),
+    ).toEqual('/dir/subdir/');
+    expect(
+      getSlug({
+        baseID: 'doc',
+        source: '@site/docs/dir/subdir/inDEx.mdx',
+        sourceDirName: '/dir/subdir',
+      }),
+    ).toEqual('/dir/subdir/');
+    expect(
+      getSlug({
+        baseID: 'doc',
+        source: '@site/docs/dir/subdir/readme.md',
+        sourceDirName: '/dir/subdir',
+      }),
+    ).toEqual('/dir/subdir/');
+    expect(
+      getSlug({
+        baseID: 'doc',
+        source: '@site/docs/dir/subdir/reADMe.mdx',
+        sourceDirName: '/dir/subdir',
+      }),
+    ).toEqual('/dir/subdir/');
+    expect(
+      getSlug({
+        baseID: 'doc',
+        source: '@site/docs/dir/subdir/subdir.md',
+        sourceDirName: '/dir/subdir',
+      }),
+    ).toEqual('/dir/subdir/');
+    expect(
+      getSlug({
+        baseID: 'doc',
+        source: '@site/docs/dir/subdir/suBDir.mdx',
+        sourceDirName: '/dir/subdir',
+      }),
+    ).toEqual('/dir/subdir/');
+  });
+
+  test('should ignore conventional doc index when explicit slug frontmatter is provided', () => {
+    expect(
+      getSlug({
+        baseID: 'doc',
+        source: '@site/docs/dir/subdir/index.md',
+        sourceDirName: '/dir/subdir',
+        frontmatterSlug: '/my/frontMatterSlug',
+      }),
+    ).toEqual('/my/frontMatterSlug');
   });
 
   test('can strip dir number prefixes', () => {
     expect(
       getSlug({
         baseID: 'doc',
-        dirName: '/001-dir1/002-dir2',
+        source: '@site/docs/001-dir1/002-dir2/doc.md',
+        sourceDirName: '/001-dir1/002-dir2',
         stripDirNumberPrefixes: true,
       }),
     ).toEqual('/dir1/dir2/doc');
     expect(
       getSlug({
         baseID: 'doc',
-        dirName: '/001-dir1/002-dir2',
+        source: '@site/docs/001-dir1/002-dir2/doc.md',
+        sourceDirName: '/001-dir1/002-dir2',
         stripDirNumberPrefixes: false,
       }),
     ).toEqual('/001-dir1/002-dir2/doc');
@@ -35,26 +103,45 @@ describe('getSlug', () => {
   // See https://github.com/facebook/docusaurus/issues/3223
   test('should handle special chars in doc path', () => {
     expect(
-      getSlug({baseID: 'my dôc', dirName: '/dir with spâce/hey $hello'}),
+      getSlug({
+        baseID: 'my dôc',
+        source: '@site/docs/dir with spâce/hey $hello/doc.md',
+        sourceDirName: '/dir with spâce/hey $hello',
+      }),
     ).toEqual('/dir with spâce/hey $hello/my dôc');
   });
 
   test('should handle current dir', () => {
-    expect(getSlug({baseID: 'doc', dirName: '.'})).toEqual('/doc');
-    expect(getSlug({baseID: 'doc', dirName: '/'})).toEqual('/doc');
+    expect(
+      getSlug({baseID: 'doc', source: '@site/docs/doc.md', sourceDirName: '.'}),
+    ).toEqual('/doc');
+    expect(
+      getSlug({baseID: 'doc', source: '@site/docs/doc.md', sourceDirName: '/'}),
+    ).toEqual('/doc');
   });
 
   test('should resolve absolute slug frontmatter', () => {
     expect(
-      getSlug({baseID: 'any', dirName: '.', frontmatterSlug: '/abc/def'}),
+      getSlug({
+        baseID: 'any',
+        source: '@site/docs/doc.md',
+        sourceDirName: '.',
+        frontmatterSlug: '/abc/def',
+      }),
     ).toEqual('/abc/def');
     expect(
-      getSlug({baseID: 'any', dirName: './any', frontmatterSlug: '/abc/def'}),
+      getSlug({
+        baseID: 'any',
+        source: '@site/docs/any/doc.md',
+        sourceDirName: './any',
+        frontmatterSlug: '/abc/def',
+      }),
     ).toEqual('/abc/def');
     expect(
       getSlug({
         baseID: 'any',
-        dirName: './any/any',
+        source: '@site/docs/any/any/doc.md',
+        sourceDirName: './any/any',
         frontmatterSlug: '/abc/def',
       }),
     ).toEqual('/abc/def');
@@ -62,46 +149,66 @@ describe('getSlug', () => {
 
   test('should resolve relative slug frontmatter', () => {
     expect(
-      getSlug({baseID: 'any', dirName: '.', frontmatterSlug: 'abc/def'}),
+      getSlug({
+        baseID: 'any',
+        source: '@site/docs/doc.md',
+        sourceDirName: '.',
+        frontmatterSlug: 'abc/def',
+      }),
     ).toEqual('/abc/def');
     expect(
-      getSlug({baseID: 'any', dirName: '/dir', frontmatterSlug: 'abc/def'}),
+      getSlug({
+        baseID: 'any',
+        source: '@site/docs/dir/doc.md',
+        sourceDirName: '/dir',
+        frontmatterSlug: 'abc/def',
+      }),
     ).toEqual('/dir/abc/def');
     expect(
       getSlug({
         baseID: 'any',
-        dirName: 'unslashedDir',
+        source: '@site/docs/unslashedDir/doc.md',
+        sourceDirName: 'unslashedDir',
         frontmatterSlug: 'abc/def',
       }),
     ).toEqual('/unslashedDir/abc/def');
     expect(
       getSlug({
         baseID: 'any',
-        dirName: 'dir/subdir',
+        source: '@site/docs/dir/subdir/doc.md',
+        sourceDirName: 'dir/subdir',
         frontmatterSlug: 'abc/def',
       }),
     ).toEqual('/dir/subdir/abc/def');
     expect(
-      getSlug({baseID: 'any', dirName: '/dir', frontmatterSlug: './abc/def'}),
+      getSlug({
+        baseID: 'any',
+        source: '@site/docs/dir/doc.md',
+        sourceDirName: '/dir',
+        frontmatterSlug: './abc/def',
+      }),
     ).toEqual('/dir/abc/def');
     expect(
       getSlug({
         baseID: 'any',
-        dirName: '/dir',
+        source: '@site/docs/dir/doc.md',
+        sourceDirName: '/dir',
         frontmatterSlug: './abc/../def',
       }),
     ).toEqual('/dir/def');
     expect(
       getSlug({
         baseID: 'any',
-        dirName: '/dir/subdir',
+        source: '@site/docs/dir/subdir/doc.md',
+        sourceDirName: '/dir/subdir',
         frontmatterSlug: '../abc/def',
       }),
     ).toEqual('/dir/abc/def');
     expect(
       getSlug({
         baseID: 'any',
-        dirName: '/dir/subdir',
+        source: '@site/docs/dir/subdirdoc.md',
+        sourceDirName: '/dir/subdir',
         frontmatterSlug: '../../../../../abc/../def',
       }),
     ).toEqual('/def');

package/src/__tests__/translations.test.ts

@@ -16,7 +16,6 @@ import {updateTranslationFileMessages} from '@docusaurus/utils';
 function createSampleDoc(doc: Pick<DocMetadata, 'id'>): DocMetadata {
   return {
     editUrl: 'any',
-    isDocsHomePage: false,
     lastUpdatedAt: 0,
     lastUpdatedBy: 'any',
     next: undefined,
@@ -40,7 +39,6 @@ function createSampleVersion(
     versionLabel: `${version.versionName} label`,
     versionPath: '/docs/',
     mainDocId: '',
-    permalinkToSidebar: {},
     routePriority: undefined,
     sidebarFilePath: 'any',
     isLast: true,
@@ -69,6 +67,13 @@ function createSampleVersion(
           type: 'category',
           label: 'Getting started',
           collapsed: false,
+          link: {
+            type: 'generated-index',
+            slug: '/category/getting-started-index-slug',
+            permalink: '/docs/category/getting-started-index-slug',
+            title: 'Getting started index title',
+            description: 'Getting started index description',
+          },
           items: [
             {
               type: 'doc',