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

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/{__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",
     },
   ],