@docusaurus/plugin-content-docs 0.0.0-4238 → 0.0.0-4243

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

@@ -12,8 +12,12 @@ import {
   collectSidebarLinks,
   transformSidebarItems,
   collectSidebarsDocIds,
+  SidebarNavigation,
+  toDocNavigationLink,
+  toNavigationLink,
 } from '../utils';
 import type {Sidebar, Sidebars} from '../types';
+import {DocMetadataBase, DocNavLink} from '../../types';
 
 describe('createSidebarsUtils', () => {
   const sidebar1: Sidebar = [
@@ -21,13 +25,13 @@ describe('createSidebarsUtils', () => {
       type: 'category',
       collapsed: false,
       collapsible: true,
-      label: 'Category1',
+      label: 'S1 Category',
       items: [
         {
           type: 'category',
           collapsed: false,
           collapsible: true,
-          label: 'Subcategory 1',
+          label: 'S1 Subcategory',
           items: [{type: 'doc', id: 'doc1'}],
         },
         {type: 'doc', id: 'doc2'},
@@ -40,7 +44,7 @@ describe('createSidebarsUtils', () => {
       type: 'category',
       collapsed: false,
       collapsible: true,
-      label: 'Category2',
+      label: 'S2 Category',
       items: [
         {type: 'doc', id: 'doc3'},
         {type: 'doc', id: 'doc4'},
@@ -48,10 +52,58 @@ describe('createSidebarsUtils', () => {
     },
   ];
 
-  const sidebars: Sidebars = {sidebar1, sidebar2};
+  const sidebar3: Sidebar = [
+    {
+      type: 'category',
+      collapsed: false,
+      collapsible: true,
+      label: 'S3 Category',
+      link: {
+        type: 'doc',
+        id: 'doc5',
+      },
+      items: [
+        {
+          type: 'category',
+          collapsed: false,
+          collapsible: true,
+          label: 'S3 SubCategory',
+          link: {
+            type: 'generated-index',
+            slug: '/s3-subcategory-index-slug',
+            permalink: '/s3-subcategory-index-permalink',
+          },
+          items: [
+            {
+              type: 'category',
+              collapsed: false,
+              collapsible: true,
+              label: 'S3 SubSubCategory',
+              link: {
+                type: 'generated-index',
+                slug: '/s3-subsubcategory-slug',
+                permalink: '/s3-subsubcategory-index-permalink',
+              },
+              items: [
+                {type: 'doc', id: 'doc6'},
+                {type: 'doc', id: 'doc7'},
+              ],
+            },
+          ],
+        },
+      ],
+    },
+  ];
+
+  const sidebars: Sidebars = {sidebar1, sidebar2, sidebar3};
 
-  const {getFirstDocIdOfFirstSidebar, getSidebarNameByDocId, getDocNavigation} =
-    createSidebarsUtils(sidebars);
+  const {
+    getFirstDocIdOfFirstSidebar,
+    getSidebarNameByDocId,
+    getDocNavigation,
+    getCategoryGeneratedIndexNavigation,
+    getCategoryGeneratedIndexList,
+  } = createSidebarsUtils(sidebars);
 
   test('getSidebarNameByDocId', async () => {
     expect(getFirstDocIdOfFirstSidebar()).toEqual('doc1');
@@ -62,32 +114,117 @@ describe('createSidebarsUtils', () => {
     expect(getSidebarNameByDocId('doc2')).toEqual('sidebar1');
     expect(getSidebarNameByDocId('doc3')).toEqual('sidebar2');
     expect(getSidebarNameByDocId('doc4')).toEqual('sidebar2');
-    expect(getSidebarNameByDocId('doc5')).toEqual(undefined);
-    expect(getSidebarNameByDocId('doc6')).toEqual(undefined);
+    expect(getSidebarNameByDocId('doc5')).toEqual('sidebar3');
+    expect(getSidebarNameByDocId('doc6')).toEqual('sidebar3');
+    expect(getSidebarNameByDocId('doc7')).toEqual('sidebar3');
+    expect(getSidebarNameByDocId('unknown_id')).toEqual(undefined);
   });
 
   test('getDocNavigation', async () => {
     expect(getDocNavigation('doc1')).toEqual({
       sidebarName: 'sidebar1',
-      previousId: undefined,
-      nextId: 'doc2',
-    });
+      previous: undefined,
+      next: {
+        type: 'doc',
+        id: 'doc2',
+      },
+    } as SidebarNavigation);
     expect(getDocNavigation('doc2')).toEqual({
       sidebarName: 'sidebar1',
-      previousId: 'doc1',
-      nextId: undefined,
-    });
+      previous: {
+        type: 'doc',
+        id: 'doc1',
+      },
+      next: undefined,
+    } as SidebarNavigation);
 
     expect(getDocNavigation('doc3')).toEqual({
       sidebarName: 'sidebar2',
-      previousId: undefined,
-      nextId: 'doc4',
-    });
+      previous: undefined,
+      next: {
+        type: 'doc',
+        id: 'doc4',
+      },
+    } as SidebarNavigation);
     expect(getDocNavigation('doc4')).toEqual({
       sidebarName: 'sidebar2',
-      previousId: 'doc3',
-      nextId: undefined,
-    });
+      previous: {
+        type: 'doc',
+        id: 'doc3',
+      },
+      next: undefined,
+    } as SidebarNavigation);
+
+    expect(getDocNavigation('doc5')).toMatchObject({
+      sidebarName: 'sidebar3',
+      previous: undefined,
+      next: {
+        type: 'category',
+        label: 'S3 SubCategory',
+      },
+    } as SidebarNavigation);
+    expect(getDocNavigation('doc6')).toMatchObject({
+      sidebarName: 'sidebar3',
+      previous: {
+        type: 'category',
+        label: 'S3 SubSubCategory',
+      },
+      next: {
+        type: 'doc',
+        id: 'doc7',
+      },
+    } as SidebarNavigation);
+    expect(getDocNavigation('doc7')).toMatchObject({
+      sidebarName: 'sidebar3',
+      previous: {
+        type: 'doc',
+        id: 'doc6',
+      },
+      next: undefined,
+    } as SidebarNavigation);
+  });
+
+  test('getCategoryGeneratedIndexNavigation', async () => {
+    expect(
+      getCategoryGeneratedIndexNavigation('/s3-subcategory-index-permalink'),
+    ).toMatchObject({
+      sidebarName: 'sidebar3',
+      previous: {
+        type: 'category',
+        label: 'S3 Category',
+      },
+      next: {
+        type: 'category',
+        label: 'S3 SubSubCategory',
+      },
+    } as SidebarNavigation);
+
+    expect(
+      getCategoryGeneratedIndexNavigation('/s3-subsubcategory-index-permalink'),
+    ).toMatchObject({
+      sidebarName: 'sidebar3',
+      previous: {
+        type: 'category',
+        label: 'S3 SubCategory',
+      },
+      next: {
+        type: 'doc',
+        id: 'doc6',
+      },
+    } as SidebarNavigation);
+  });
+
+  test('getCategoryGeneratedIndexList', async () => {
+    expect(getCategoryGeneratedIndexList()).toMatchObject([
+      {
+        type: 'category',
+        label: 'S3 SubCategory',
+      },
+      {
+        type: 'category',
+        label: 'S3 SubSubCategory',
+      },
+    ]);
   });
 });
 
@@ -393,3 +530,166 @@ describe('transformSidebarItems', () => {
     ]);
   });
 });
+
+describe('toDocNavigationLink', () => {
+  type TestDoc = Pick<DocMetadataBase, 'permalink' | 'title' | 'frontMatter'>;
+  function testDoc(data: TestDoc) {
+    return data as DocMetadataBase;
+  }
+
+  test('with no frontmatter', () => {
+    expect(
+      toDocNavigationLink(
+        testDoc({
+          title: 'Doc Title',
+          permalink: '/docPermalink',
+          frontMatter: {},
+        }),
+      ),
+    ).toEqual({
+      title: 'Doc Title',
+      permalink: '/docPermalink',
+    } as DocNavLink);
+  });
+
+  test('with pagination_label frontmatter', () => {
+    expect(
+      toDocNavigationLink(
+        testDoc({
+          title: 'Doc Title',
+          permalink: '/docPermalink',
+          frontMatter: {
+            pagination_label: 'pagination_label',
+          },
+        }),
+      ),
+    ).toEqual({
+      title: 'pagination_label',
+      permalink: '/docPermalink',
+    } as DocNavLink);
+  });
+
+  test('with sidebar_label frontmatter', () => {
+    expect(
+      toDocNavigationLink(
+        testDoc({
+          title: 'Doc Title',
+          permalink: '/docPermalink',
+          frontMatter: {
+            sidebar_label: 'sidebar_label',
+          },
+        }),
+      ),
+    ).toEqual({
+      title: 'sidebar_label',
+      permalink: '/docPermalink',
+    } as DocNavLink);
+  });
+
+  test('with pagination_label + sidebar_label frontmatter', () => {
+    expect(
+      toDocNavigationLink(
+        testDoc({
+          title: 'Doc Title',
+          permalink: '/docPermalink',
+          frontMatter: {
+            pagination_label: 'pagination_label',
+            sidebar_label: 'sidebar_label',
+          },
+        }),
+      ),
+    ).toEqual({
+      title: 'pagination_label',
+      permalink: '/docPermalink',
+    } as DocNavLink);
+  });
+});
+
+describe('toNavigationLink', () => {
+  type TestDoc = Pick<DocMetadataBase, 'permalink' | 'title'>;
+  function testDoc(data: TestDoc) {
+    return {...data, frontMatter: {}} as DocMetadataBase;
+  }
+
+  const docsById: Record<string, DocMetadataBase> = {
+    doc1: testDoc({
+      title: 'Doc 1',
+      permalink: '/doc1',
+    }),
+    doc2: testDoc({
+      title: 'Doc 1',
+      permalink: '/doc1',
+    }),
+  };
+
+  test('with doc items', () => {
+    expect(toNavigationLink({type: 'doc', id: 'doc1'}, docsById)).toEqual(
+      toDocNavigationLink(docsById.doc1),
+    );
+    expect(toNavigationLink({type: 'doc', id: 'doc2'}, docsById)).toEqual(
+      toDocNavigationLink(docsById.doc2),
+    );
+    expect(() =>
+      toNavigationLink({type: 'doc', id: 'doc3'}, docsById),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `"Can't create navigation link: no doc found with id=doc3"`,
+    );
+  });
+
+  test('with category item and doc link', () => {
+    expect(
+      toNavigationLink(
+        {
+          type: 'category',
+          label: 'Category',
+          items: [],
+          link: {
+            type: 'doc',
+            id: 'doc1',
+          },
+          collapsed: true,
+          collapsible: true,
+        },
+        docsById,
+      ),
+    ).toEqual(toDocNavigationLink(docsById.doc1));
+    expect(() =>
+      toNavigationLink(
+        {
+          type: 'category',
+          label: 'Category',
+          items: [],
+          link: {
+            type: 'doc',
+            id: 'doc3',
+          },
+          collapsed: true,
+          collapsible: true,
+        },
+        docsById,
+      ),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `"Can't create navigation link: no doc found with id=doc3"`,
+    );
+  });
+
+  test('with category item and generated-index link', () => {
+    expect(
+      toNavigationLink(
+        {
+          type: 'category',
+          label: 'Category',
+          items: [],
+          link: {
+            type: 'generated-index',
+            slug: 'slug',
+            permalink: 'generated-index-permalink',
+          },
+          collapsed: true,
+          collapsible: true,
+        },
+        docsById,
+      ),
+    ).toEqual({title: 'Category', permalink: 'generated-index-permalink'});
+  });
+});

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

@@ -0,0 +1,105 @@
+/**
+ * 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 {validateSidebars, validateCategoryMetadataFile} from '../validation';
+import {CategoryMetadataFile} from '../generator';
+import {SidebarsConfig} from '../types';
+
+describe('validateSidebars', () => {
+  // TODO add more tests
+
+  // TODO it seems many error cases are not validated properly
+  // and error messages are quite bad
+  test('throw for bad value', async () => {
+    expect(() => validateSidebars({sidebar: [{type: 42}]}))
+      .toThrowErrorMatchingInlineSnapshot(`
+      "{
+        \\"type\\": 42,
+        \\"undefined\\" [1]: -- missing --
+      }
+      
+      [1] Unknown sidebar item type \\"42\\"."
+    `);
+  });
+
+  test('accept empty object', async () => {
+    const sidebars: SidebarsConfig = {};
+    validateSidebars(sidebars);
+  });
+
+  test('accept valid values', async () => {
+    const sidebars: SidebarsConfig = {
+      sidebar1: [
+        {type: 'doc', id: 'doc1'},
+        {type: 'doc', id: 'doc2'},
+        {
+          type: 'category',
+          label: 'Category',
+          items: [{type: 'doc', id: 'doc3'}],
+        },
+      ],
+    };
+    validateSidebars(sidebars);
+  });
+});
+
+describe('validateCategoryMetadataFile', () => {
+  // TODO add more tests
+
+  test('throw for bad value', async () => {
+    expect(() =>
+      validateCategoryMetadataFile(42),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `"\\"value\\" must be of type object"`,
+    );
+  });
+
+  test('accept empty object', async () => {
+    const content: CategoryMetadataFile = {};
+    expect(validateCategoryMetadataFile(content)).toEqual(content);
+  });
+
+  test('accept valid values', async () => {
+    const content: CategoryMetadataFile = {
+      className: 'className',
+      label: 'Category Label',
+      link: {
+        type: 'generated-index',
+        slug: 'slug',
+        title: 'title',
+        description: 'description',
+      },
+      collapsible: true,
+      collapsed: true,
+      position: 3,
+    };
+    expect(validateCategoryMetadataFile(content)).toEqual(content);
+  });
+
+  test('rejects permalink', async () => {
+    const content: CategoryMetadataFile = {
+      className: 'className',
+      label: 'Category Label',
+      link: {
+        type: 'generated-index',
+        slug: 'slug',
+        // @ts-expect-error: rejected on purpose
+        permalink: 'somePermalink',
+        title: 'title',
+        description: 'description',
+      },
+      collapsible: true,
+      collapsed: true,
+      position: 3,
+    };
+    expect(() =>
+      validateCategoryMetadataFile(content),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `"\\"link.permalink\\" is not allowed"`,
+    );
+  });
+});

package/src/sidebars/generator.ts

@@ -11,19 +11,27 @@ import type {
   SidebarItemCategory,
   SidebarItemsGenerator,
   SidebarItemsGeneratorDoc,
+  SidebarItemCategoryLink,
+  SidebarItemCategoryLinkConfig,
 } from './types';
-import {keyBy, sortBy} from 'lodash';
+import {sortBy, last} from 'lodash';
 import {addTrailingSlash, posixPath} from '@docusaurus/utils';
-import {Joi} from '@docusaurus/utils-validation';
 import chalk from 'chalk';
 import path from 'path';
 import fs from 'fs-extra';
 import Yaml from 'js-yaml';
+import {validateCategoryMetadataFile} from './validation';
+import {createDocsByIdIndex, isConventionalDocIndex} from '../docs';
 
 const BreadcrumbSeparator = '/';
 // To avoid possible name clashes with a folder of the same name as the ID
 const docIdPrefix = '$doc$/';
 
+// Just an alias to the make code more explicit
+function getLocalDocId(docId: string): string {
+  return last(docId.split('/'))!;
+}
+
 export const CategoryMetadataFilenameBase = '_category_';
 export const CategoryMetadataFilenamePattern = '_category_.{json,yml,yaml}';
 
@@ -33,6 +41,7 @@ export type CategoryMetadataFile = {
   collapsed?: boolean;
   collapsible?: boolean;
   className?: string;
+  link?: SidebarItemCategoryLinkConfig;
 
   // TODO should we allow "items" here? how would this work? would an "autogenerated" type be allowed?
   // This mkdocs plugin do something like that: https://github.com/lukasgeiter/mkdocs-awesome-pages-plugin/
@@ -50,17 +59,9 @@ type Dir = {
   [item: string]: Dir | null;
 };
 
-const CategoryMetadataFileSchema = Joi.object<CategoryMetadataFile>({
-  label: Joi.string(),
-  position: Joi.number(),
-  collapsed: Joi.boolean(),
-  collapsible: Joi.boolean(),
-  className: Joi.string(),
-});
-
 // TODO I now believe we should read all the category metadata files ahead of time: we may need this metadata to customize docs metadata
 // Example use-case being able to disable number prefix parsing at the folder level, or customize the default route path segment for an intermediate directory...
-// TODO later if there is `CategoryFolder/index.md`, we may want to read the metadata as yaml on it
+// TODO later if there is `CategoryFolder/with-category-name-doc.md`, we may want to read the metadata as yaml on it
 // see https://github.com/facebook/docusaurus/issues/3464#issuecomment-818670449
 async function readCategoryMetadataFile(
   categoryDirPath: string,
@@ -69,7 +70,7 @@ async function readCategoryMetadataFile(
     const contentString = await fs.readFile(filePath, {encoding: 'utf8'});
     const unsafeContent = Yaml.load(contentString);
     try {
-      return Joi.attempt(unsafeContent, CategoryMetadataFileSchema);
+      return validateCategoryMetadataFile(unsafeContent);
     } catch (e) {
       console.error(
         chalk.red(
@@ -100,6 +101,21 @@ export const DefaultSidebarItemsGenerator: SidebarItemsGenerator = async ({
   item: {dirName: autogenDir},
   version,
 }) => {
+  const docsById = createDocsByIdIndex(allDocs);
+  const findDoc = (docId: string): SidebarItemsGeneratorDoc | undefined =>
+    docsById[docId];
+  const getDoc = (docId: string): SidebarItemsGeneratorDoc => {
+    const doc = findDoc(docId);
+    if (!doc) {
+      throw new Error(
+        `Can't find any doc with id=${docId}.\nAvailable doc ids:\n- ${Object.keys(
+          docsById,
+        ).join('\n- ')}`,
+      );
+    }
+    return doc;
+  };
+
   /**
    * Step 1. Extract the docs that are in the autogen dir.
    */
@@ -163,12 +179,11 @@ export const DefaultSidebarItemsGenerator: SidebarItemsGenerator = async ({
    * (From a record to an array of items, akin to normalizing shorthand)
    */
   function generateSidebar(fsModel: Dir): Promise<WithPosition<SidebarItem>[]> {
-    const docsById = keyBy(allDocs, (doc) => doc.id);
     function createDocItem(id: string): WithPosition<SidebarItemDoc> {
       const {
         sidebarPosition: position,
         frontMatter: {sidebar_label: label, sidebar_class_name: className},
-      } = docsById[id];
+      } = getDoc(id);
       return {
         type: 'doc',
         id,
@@ -187,6 +202,57 @@ export const DefaultSidebarItemsGenerator: SidebarItemsGenerator = async ({
       const categoryMetadata = await readCategoryMetadataFile(categoryPath);
       const className = categoryMetadata?.className;
       const {filename, numberPrefix} = numberPrefixParser(folderName);
+      const allItems = await Promise.all(
+        Object.entries(dir).map(([key, content]) =>
+          dirToItem(content, key, `${fullPath}/${key}`),
+        ),
+      );
+
+      // Try to match a doc inside the category folder,
+      // using the "local id" (myDoc) or "qualified id" (dirName/myDoc)
+      function findDocByLocalId(localId: string): SidebarItemDoc | undefined {
+        return allItems.find(
+          (item) => item.type === 'doc' && getLocalDocId(item.id) === localId,
+        ) as SidebarItemDoc | undefined;
+      }
+
+      function findConventionalCategoryDocLink(): SidebarItemDoc | undefined {
+        return allItems.find(
+          (item) =>
+            item.type === 'doc' && isConventionalDocIndex(getDoc(item.id)),
+        ) as SidebarItemDoc | undefined;
+      }
+
+      function getCategoryLinkedDocId(): string | undefined {
+        const link = categoryMetadata?.link;
+        if (link) {
+          if (link.type === 'doc') {
+            return findDocByLocalId(link.id)?.id || getDoc(link.id).id;
+          } else {
+            // We don't continue for other link types on purpose!
+            // IE if user decide to use type "generated-index", we should not pick a README.md file as the linked doc
+            return undefined;
+          }
+        }
+        // Apply default convention to pick index.md, README.md or <categoryName>.md as the category doc
+        return findConventionalCategoryDocLink()?.id;
+      }
+
+      const categoryLinkedDocId = getCategoryLinkedDocId();
+
+      const link: SidebarItemCategoryLink | undefined = categoryLinkedDocId
+        ? {
+            type: 'doc',
+            id: categoryLinkedDocId, // We "remap" a potentially "local id" to a "qualified id"
+          }
+        : // TODO typing issue
+          (categoryMetadata?.link as SidebarItemCategoryLink | undefined);
+
+      // If a doc is linked, remove it from the category subItems
+      const items = allItems.filter(
+        (item) => !(item.type === 'doc' && item.id === categoryLinkedDocId),
+      );
+
       return {
         type: 'category',
         label: categoryMetadata?.label ?? filename,
@@ -195,11 +261,8 @@ export const DefaultSidebarItemsGenerator: SidebarItemsGenerator = async ({
         collapsed: categoryMetadata?.collapsed ?? options.sidebarCollapsed,
         position: categoryMetadata?.position ?? numberPrefix,
         ...(className !== undefined && {className}),
-        items: await Promise.all(
-          Object.entries(dir).map(([key, content]) =>
-            dirToItem(content, key, `${fullPath}/${key}`),
-          ),
-        ),
+        items,
+        ...(link && {link}),
       };
     }
     async function dirToItem(