fix(v2): more consistent route config generation (#1946)

* fix(v2): more consistent route config generation

* nits

* snapshot

* address review & test upd

* reduce 2xloop -> 1x loop in docs plugin

* nits

CHANGELOG-2.x.md

@@ -2,6 +2,7 @@
 
 ## Unreleased
 
+- Ensure routes config generation to be more consistent in ordering. Nested routes should be placed last in routes.js. This will allow user to create `src/pages/docs.js` to create custom docs page for `/docs` or even `src/pages/docs/super.js` to create page for `/docs/super/`;
 - Fix watcher does not trigger reload on windows.
 - Add feed for blog posts.
 - **HOTFIX for 2.0.0-alpha.32** - Fix build compilation if exists only one code tab.

packages/docusaurus-plugin-content-docs/src/__tests__/__snapshots__/index.test.ts.snap

@@ -55,9 +55,9 @@ Array [
   Object {
     "component": "@theme/DocPage",
     "modules": Object {
-      "docsMetadata": "@docusaurus-plugin-content-docs/docs-b5f.json",
+      "docsMetadata": "@docusaurus-plugin-content-docs/docs-route-ff2.json",
     },
-    "path": "/docs",
+    "path": "/docs/:route",
     "routes": Array [
       Object {
         "component": "@theme/DocItem",

packages/docusaurus-plugin-content-docs/src/index.ts

@@ -9,7 +9,7 @@ import globby from 'globby';
 import fs from 'fs-extra';
 import path from 'path';
 import {idx, normalizeUrl, docuHash} from '@docusaurus/utils';
-import {LoadContext, Plugin, DocusaurusConfig} from '@docusaurus/types';
+import {LoadContext, Plugin} from '@docusaurus/types';
 
 import createOrder from './order';
 import loadSidebars from './sidebars';
@@ -117,6 +117,7 @@ export default function pluginContentDocs(
 
       // Construct docsMetadata
       const docsMetadata: DocsMetadata = {};
+      const permalinkToSidebar: PermalinkToSidebar = {};
       Object.keys(docsMetadataRaw).forEach(currentID => {
         let previous;
         let next;
@@ -139,10 +140,9 @@ export default function pluginContentDocs(
           previous,
           next,
         };
-      });
 
-      const permalinkToSidebar: PermalinkToSidebar = {};
-      Object.values(docsMetadataRaw).forEach(({source, permalink, sidebar}) => {
+        // sourceToPermalink and permalinkToSidebar mapping
+        const {source, permalink, sidebar} = docsMetadataRaw[currentID];
         sourceToPermalink[source] = permalink;
         if (sidebar) {
           permalinkToSidebar[permalink] = sidebar;
@@ -240,8 +240,9 @@ export default function pluginContentDocs(
       };
 
       const docsBaseRoute = normalizeUrl([
-        (context.siteConfig as DocusaurusConfig).baseUrl,
+        context.baseUrl,
         routeBasePath,
+        ':route',
       ]);
       const docsBaseMetadataPath = await createData(
         `${docuHash(docsBaseRoute)}.json`,

packages/docusaurus/src/server/__tests__/__snapshots__/routes.test.ts.snap

@@ -80,8 +80,8 @@ Object {
       "loader": "() => import(/* webpackChunkName: 'content---docs-helloaff-811' */ \\"docs/hello.md\\")",
       "modulePath": "docs/hello.md",
     },
-    "docsMetadata---docsf-34-2ab": Object {
-      "loader": "() => import(/* webpackChunkName: 'docsMetadata---docsf-34-2ab' */ \\"docs-b5f.json\\")",
+    "docsMetadata---docs-routef-34-881": Object {
+      "loader": "() => import(/* webpackChunkName: 'docsMetadata---docs-routef-34-881' */ \\"docs-b5f.json\\")",
       "modulePath": "docs-b5f.json",
     },
     "metadata---docs-foo-baz-2-cf-fa7": Object {
@@ -94,15 +94,15 @@ Object {
     },
   },
   "routesChunkNames": Object {
-    "/docs": Object {
-      "component": "component---theme-doc-page-1-be-9be",
-      "docsMetadata": "docsMetadata---docsf-34-2ab",
-    },
     "/docs/hello": Object {
       "component": "component---theme-doc-item-178-a40",
       "content": "content---docs-helloaff-811",
       "metadata": "metadata---docs-hello-956-741",
     },
+    "/docs:route": Object {
+      "component": "component---theme-doc-page-1-be-9be",
+      "docsMetadata": "docsMetadata---docs-routef-34-881",
+    },
     "docs/foo/baz": Object {
       "component": "component---theme-doc-item-178-a40",
       "content": "content---docs-foo-baz-8-ce-61e",
@@ -116,8 +116,8 @@ import ComponentCreator from '@docusaurus/ComponentCreator';
 export default [
   
 {
-  path: '/docs',
-  component: ComponentCreator('/docs'),
+  path: '/docs:route',
+  component: ComponentCreator('/docs:route'),
   
   routes: [
 {

packages/docusaurus/src/server/__tests__/routes.test.ts

@@ -5,13 +5,14 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import {loadRoutes, RouteConfig} from '../routes';
+import {loadRoutes} from '../routes';
+import {RouteConfig} from '@docusaurus/types';
 
 describe('loadRoutes', () => {
   test('nested route config', async () => {
     const nestedRouteConfig: RouteConfig = {
       component: '@theme/DocPage',
-      path: '/docs',
+      path: '/docs:route',
       modules: {
         docsMetadata: 'docs-b5f.json',
       },

packages/docusaurus/src/server/plugins/index.ts

@@ -75,6 +75,17 @@ export async function loadPlugins({
     }),
   );
 
+  // Sort the route config. This ensures that route with nested routes is always placed last
+  pluginsRouteConfigs.sort((a, b) => {
+    if (a.routes && !b.routes) {
+      return 1;
+    }
+    if (!a.routes && b.routes) {
+      return -1;
+    }
+    return a.path > b.path ? 1 : b.path > a.path ? -1 : 0;
+  });
+
   return {
     plugins,
     pluginsRouteConfigs,