@docusaurus/plugin-content-docs 0.0.0-4240 → 0.0.0-4244

package/src/props.ts

@@ -8,25 +8,28 @@
 import type {LoadedVersion, VersionTag, DocMetadata} from './types';
 import type {
   SidebarItemDoc,
-  SidebarItemLink,
   SidebarItem,
+  SidebarItemCategory,
+  SidebarItemCategoryLink,
+  PropVersionDocs,
 } from './sidebars/types';
 import type {
   PropSidebars,
   PropVersionMetadata,
   PropSidebarItem,
+  PropSidebarItemCategory,
   PropTagDocList,
   PropTagDocListDoc,
+  PropSidebarItemLink,
 } from '@docusaurus/plugin-content-docs';
 import {compact, keyBy, mapValues} from 'lodash';
+import {createDocsByIdIndex} from './docs';
 
 export function toSidebarsProp(loadedVersion: LoadedVersion): PropSidebars {
-  const docsById = keyBy(loadedVersion.docs, (doc) => doc.id);
+  const docsById = createDocsByIdIndex(loadedVersion.docs);
 
-  const convertDocLink = (item: SidebarItemDoc): SidebarItemLink => {
-    const docId = item.id;
+  function getDocById(docId: string): DocMetadata {
     const docMetadata = docsById[docId];
-
     if (!docMetadata) {
       throw new Error(
         `Invalid sidebars file. The document with id "${docId}" was used in the sidebar, but no document with this id could be found.
@@ -34,26 +37,49 @@ Available document ids are:
 - ${Object.keys(docsById).sort().join('\n- ')}`,
       );
     }
+    return docMetadata;
+  }
 
+  const convertDocLink = (item: SidebarItemDoc): PropSidebarItemLink => {
+    const docMetadata = getDocById(item.id);
     const {
       title,
       permalink,
       frontMatter: {sidebar_label: sidebarLabel},
     } = docMetadata;
-
     return {
       type: 'link',
       label: sidebarLabel || item.label || title,
       href: permalink,
       className: item.className,
       customProps: item.customProps,
+      docId: docMetadata.unversionedId,
     };
   };
 
-  const normalizeItem = (item: SidebarItem): PropSidebarItem => {
+  function getCategoryLinkHref(
+    link: SidebarItemCategoryLink | undefined,
+  ): string | undefined {
+    switch (link?.type) {
+      case 'doc':
+        return getDocById(link.id).permalink;
+      case 'generated-index':
+        return link.permalink;
+      default:
+        return undefined;
+    }
+  }
+
+  function convertCategory(item: SidebarItemCategory): PropSidebarItemCategory {
+    const {link, ...rest} = item;
+    const href = getCategoryLinkHref(link);
+    return {...rest, items: item.items.map(normalizeItem), ...(href && {href})};
+  }
+
+  function normalizeItem(item: SidebarItem): PropSidebarItem {
     switch (item.type) {
       case 'category':
-        return {...item, items: item.items.map(normalizeItem)};
+        return convertCategory(item);
       case 'ref':
       case 'doc':
         return convertDocLink(item);
@@ -61,7 +87,7 @@ Available document ids are:
       default:
         return item;
     }
-  };
+  }
 
   // Transform the sidebar so that all sidebar item will be in the
   // form of 'link' or 'category' only.
@@ -69,6 +95,18 @@ Available document ids are:
   return mapValues(loadedVersion.sidebars, (items) => items.map(normalizeItem));
 }
 
+function toVersionDocsProp(loadedVersion: LoadedVersion): PropVersionDocs {
+  return mapValues(
+    keyBy(loadedVersion.docs, (doc) => doc.unversionedId),
+    (doc) => ({
+      id: doc.unversionedId,
+      title: doc.title,
+      description: doc.description,
+      sidebar: doc.sidebar,
+    }),
+  );
+}
+
 export function toVersionMetadataProp(
   pluginId: string,
   loadedVersion: LoadedVersion,
@@ -82,6 +120,7 @@ export function toVersionMetadataProp(
     className: loadedVersion.versionClassName,
     isLast: loadedVersion.isLast,
     docsSidebars: toSidebarsProp(loadedVersion),
+    docs: toVersionDocsProp(loadedVersion),
   };
 }
 

package/src/routes.ts

@@ -0,0 +1,173 @@
+/**
+ * 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 {PluginContentLoadedActions, RouteConfig} from '@docusaurus/types';
+import {docuHash, createSlugger} from '@docusaurus/utils';
+import {
+  CategoryGeneratedIndexMetadata,
+  DocMetadata,
+  LoadedVersion,
+} from './types';
+import type {PropCategoryGeneratedIndex} from '@docusaurus/plugin-content-docs';
+import {toVersionMetadataProp} from './props';
+import chalk from 'chalk';
+
+export async function createCategoryGeneratedIndexRoutes({
+  version,
+  actions,
+  docCategoryGeneratedIndexComponent,
+}: {
+  version: LoadedVersion;
+  actions: PluginContentLoadedActions;
+  docCategoryGeneratedIndexComponent: string;
+}): Promise<RouteConfig[]> {
+  const slugs = createSlugger();
+
+  async function createCategoryGeneratedIndexRoute(
+    categoryGeneratedIndex: CategoryGeneratedIndexMetadata,
+  ): Promise<RouteConfig> {
+    const {sidebar, title, description, slug, permalink, previous, next} =
+      categoryGeneratedIndex;
+
+    const propFileName = slugs.slug(
+      `${version.versionPath}-${categoryGeneratedIndex.sidebar}-category-${categoryGeneratedIndex.title}`,
+    );
+
+    const prop: PropCategoryGeneratedIndex = {
+      title,
+      description,
+      slug,
+      permalink,
+      navigation: {
+        previous,
+        next,
+      },
+    };
+
+    const propData = await actions.createData(
+      `${docuHash(`category/${propFileName}`)}.json`,
+      JSON.stringify(prop, null, 2),
+    );
+
+    return {
+      path: permalink,
+      component: docCategoryGeneratedIndexComponent,
+      exact: true,
+      modules: {
+        categoryGeneratedIndex: propData,
+      },
+      // Same as doc, this sidebar route attribute permits to associate this subpage to the given sidebar
+      ...(sidebar && {sidebar}),
+    };
+  }
+
+  return Promise.all(
+    version.categoryGeneratedIndices.map(createCategoryGeneratedIndexRoute),
+  );
+}
+
+export async function createDocRoutes({
+  docs,
+  actions,
+  docItemComponent,
+}: {
+  docs: DocMetadata[];
+  actions: PluginContentLoadedActions;
+  docItemComponent: string;
+}): Promise<RouteConfig[]> {
+  return Promise.all(
+    docs.map(async (metadataItem) => {
+      await actions.createData(
+        // Note that this created data path must be in sync with
+        // metadataPath provided to mdx-loader.
+        `${docuHash(metadataItem.source)}.json`,
+        JSON.stringify(metadataItem, null, 2),
+      );
+
+      const docRoute: RouteConfig = {
+        path: metadataItem.permalink,
+        component: docItemComponent,
+        exact: true,
+        modules: {
+          content: metadataItem.source,
+        },
+        // Because the parent (DocPage) comp need to access it easily
+        // This permits to render the sidebar once without unmount/remount when navigating (and preserve sidebar state)
+        ...(metadataItem.sidebar && {
+          sidebar: metadataItem.sidebar,
+        }),
+      };
+
+      return docRoute;
+    }),
+  );
+}
+
+export async function createVersionRoutes({
+  loadedVersion,
+  actions,
+  docItemComponent,
+  docLayoutComponent,
+  docCategoryGeneratedIndexComponent,
+  pluginId,
+  aliasedSource,
+}: {
+  loadedVersion: LoadedVersion;
+  actions: PluginContentLoadedActions;
+  docLayoutComponent: string;
+  docItemComponent: string;
+  docCategoryGeneratedIndexComponent: string;
+  pluginId: string;
+  aliasedSource: (str: string) => string;
+}): Promise<void> {
+  async function doCreateVersionRoutes(version: LoadedVersion): Promise<void> {
+    const versionMetadata = toVersionMetadataProp(pluginId, version);
+    const versionMetadataPropPath = await actions.createData(
+      `${docuHash(`version-${version.versionName}-metadata-prop`)}.json`,
+      JSON.stringify(versionMetadata, null, 2),
+    );
+
+    async function createVersionSubRoutes() {
+      const [docRoutes, sidebarsRoutes] = await Promise.all([
+        createDocRoutes({docs: version.docs, actions, docItemComponent}),
+        createCategoryGeneratedIndexRoutes({
+          version,
+          actions,
+          docCategoryGeneratedIndexComponent,
+        }),
+      ]);
+
+      const routes = [...docRoutes, ...sidebarsRoutes];
+      return routes.sort((a, b) => a.path.localeCompare(b.path));
+    }
+
+    actions.addRoute({
+      path: version.versionPath,
+      // allow matching /docs/* as well
+      exact: false,
+      // main docs component (DocPage)
+      component: docLayoutComponent,
+      // sub-routes for each doc
+      routes: await createVersionSubRoutes(),
+      modules: {
+        versionMetadata: aliasedSource(versionMetadataPropPath),
+      },
+      priority: version.routePriority,
+    });
+  }
+
+  try {
+    return await doCreateVersionRoutes(loadedVersion);
+  } catch (e) {
+    console.error(
+      chalk.red(
+        `Can't create version routes for version "${loadedVersion.versionName}"`,
+      ),
+    );
+    throw e;
+  }
+}

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

@@ -1,6 +1,6 @@
 // Jest Snapshot v1, https://goo.gl/fbAQLP
 
-exports[`loadUnprocessedSidebars sidebars link 1`] = `
+exports[`loadNormalizedSidebars sidebars link 1`] = `
 Object {
   "docs": Array [
     Object {
@@ -14,13 +14,14 @@ Object {
         },
       ],
       "label": "Test",
+      "link": undefined,
       "type": "category",
     },
   ],
 }
 `;
 
-exports[`loadUnprocessedSidebars sidebars with category.collapsed property 1`] = `
+exports[`loadNormalizedSidebars sidebars with category.collapsed property 1`] = `
 Object {
   "docs": Array [
     Object {
@@ -37,10 +38,12 @@ Object {
             },
           ],
           "label": "Introduction",
+          "link": undefined,
           "type": "category",
         },
       ],
       "label": "Test",
+      "link": undefined,
       "type": "category",
     },
     Object {
@@ -57,17 +60,19 @@ Object {
             },
           ],
           "label": "Powering MDX",
+          "link": undefined,
           "type": "category",
         },
       ],
       "label": "Reference",
+      "link": undefined,
       "type": "category",
     },
   ],
 }
 `;
 
-exports[`loadUnprocessedSidebars sidebars with category.collapsed property at first level 1`] = `
+exports[`loadNormalizedSidebars sidebars with category.collapsed property at first level 1`] = `
 Object {
   "docs": Array [
     Object {
@@ -80,6 +85,7 @@ Object {
         },
       ],
       "label": "Introduction",
+      "link": undefined,
       "type": "category",
     },
     Object {
@@ -92,13 +98,14 @@ Object {
         },
       ],
       "label": "Powering MDX",
+      "link": undefined,
       "type": "category",
     },
   ],
 }
 `;
 
-exports[`loadUnprocessedSidebars sidebars with deep level of category 1`] = `
+exports[`loadNormalizedSidebars sidebars with deep level of category 1`] = `
 Object {
   "docs": Array [
     Object {
@@ -139,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 {
@@ -155,17 +165,19 @@ Object {
             },
           ],
           "label": "level 2",
+          "link": undefined,
           "type": "category",
         },
       ],
       "label": "level 1",
+      "link": undefined,
       "type": "category",
     },
   ],
 }
 `;
 
-exports[`loadUnprocessedSidebars sidebars with first level not a category 1`] = `
+exports[`loadNormalizedSidebars sidebars with first level not a category 1`] = `
 Object {
   "docs": Array [
     Object {
@@ -178,6 +190,7 @@ Object {
         },
       ],
       "label": "Getting Started",
+      "link": undefined,
       "type": "category",
     },
     Object {
@@ -188,7 +201,7 @@ Object {
 }
 `;
 
-exports[`loadUnprocessedSidebars sidebars with known sidebar item type 1`] = `
+exports[`loadNormalizedSidebars sidebars with known sidebar item type 1`] = `
 Object {
   "docs": Array [
     Object {
@@ -214,6 +227,7 @@ Object {
         },
       ],
       "label": "Test",
+      "link": undefined,
       "type": "category",
     },
     Object {
@@ -226,6 +240,7 @@ Object {
         },
       ],
       "label": "Guides",
+      "link": undefined,
       "type": "category",
     },
   ],

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

@@ -129,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',
+        },
       },
     });
 
@@ -153,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',
@@ -167,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',
@@ -209,6 +228,10 @@ describe('DefaultSidebarItemsGenerator', () => {
         label: 'Tutorials',
         collapsed: true,
         collapsible: true,
+        link: {
+          type: 'doc',
+          id: 'tutorials-index',
+        },
         items: [
           {type: 'doc', id: 'tutorial1'},
           {type: 'doc', id: 'tutorial2'},
@@ -219,6 +242,10 @@ describe('DefaultSidebarItemsGenerator', () => {
         label: 'Guides',
         collapsed: false,
         collapsible: true,
+        link: {
+          type: 'doc',
+          id: 'guides-index',
+        },
         items: [
           {type: 'doc', id: 'guide1'},
           {
@@ -227,6 +254,12 @@ describe('DefaultSidebarItemsGenerator', () => {
             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'},
         ],
@@ -354,4 +387,75 @@ describe('DefaultSidebarItemsGenerator', () => {
       },
     ] 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);
+  });
 });