@docusaurus/plugin-content-docs 0.0.0-5264 → 0.0.0-5265

package/lib/index.js

@@ -19,10 +19,7 @@ const versions_1 = require("./versions");
 const cli_1 = require("./cli");
 const constants_1 = require("./constants");
 const globalData_1 = require("./globalData");
-const props_1 = require("./props");
-const categoryGeneratedIndex_1 = require("./categoryGeneratedIndex");
 const translations_1 = require("./translations");
-const tags_1 = require("./tags");
 const routes_1 = require("./routes");
 const utils_2 = require("./sidebars/utils");
 async function pluginContentDocs(context, options) {
@@ -125,77 +122,18 @@ async function pluginContentDocs(context, options) {
             return (0, translations_1.translateLoadedContent)(content, translationFiles);
         },
         async contentLoaded({ content, actions }) {
-            const { loadedVersions } = content;
-            const { docLayoutComponent, docItemComponent, docCategoryGeneratedIndexComponent, breadcrumbs, } = options;
-            const { addRoute, createData, setGlobalData } = actions;
-            const versions = loadedVersions.map((version) => {
-                const sidebarsUtils = (0, utils_2.createSidebarsUtils)(version.sidebars);
-                return {
-                    ...version,
-                    sidebarsUtils,
-                    categoryGeneratedIndices: (0, categoryGeneratedIndex_1.getCategoryGeneratedIndexMetadataList)({
-                        docs: version.docs,
-                        sidebarsUtils,
-                    }),
-                };
-            });
-            async function createVersionTagsRoutes(version) {
-                const versionTags = (0, tags_1.getVersionTags)(version.docs);
-                // TODO tags should be a sub route of the version route
-                async function createTagsListPage() {
-                    const tagsProp = Object.values(versionTags).map((tagValue) => ({
-                        label: tagValue.label,
-                        permalink: tagValue.permalink,
-                        count: tagValue.docIds.length,
-                    }));
-                    // Only create /tags page if there are tags.
-                    if (tagsProp.length > 0) {
-                        const tagsPropPath = await createData(`${(0, utils_1.docuHash)(`tags-list-${version.versionName}-prop`)}.json`, JSON.stringify(tagsProp, null, 2));
-                        addRoute({
-                            path: version.tagsPath,
-                            exact: true,
-                            component: options.docTagsListComponent,
-                            modules: {
-                                tags: aliasedSource(tagsPropPath),
-                            },
-                        });
-                    }
-                }
-                // TODO tags should be a sub route of the version route
-                async function createTagDocListPage(tag) {
-                    const tagProps = (0, props_1.toTagDocListProp)({
-                        allTagsPath: version.tagsPath,
-                        tag,
-                        docs: version.docs,
-                    });
-                    const tagPropPath = await createData(`${(0, utils_1.docuHash)(`tag-${tag.permalink}`)}.json`, JSON.stringify(tagProps, null, 2));
-                    addRoute({
-                        path: tag.permalink,
-                        component: options.docTagDocListComponent,
-                        exact: true,
-                        modules: {
-                            tag: aliasedSource(tagPropPath),
-                        },
-                    });
-                }
-                await createTagsListPage();
-                await Promise.all(Object.values(versionTags).map(createTagDocListPage));
-            }
-            await Promise.all(versions.map((version) => (0, routes_1.createVersionRoutes)({
-                version,
-                docItemComponent,
-                docLayoutComponent,
-                docCategoryGeneratedIndexComponent,
-                pluginId,
-                aliasedSource,
+            const versions = content.loadedVersions.map(versions_1.toFullVersion);
+            await (0, routes_1.createAllRoutes)({
+                baseUrl,
+                versions,
+                options,
                 actions,
-            })));
-            // TODO tags should be a sub route of the version route
-            await Promise.all(versions.map(createVersionTagsRoutes));
-            setGlobalData({
+                aliasedSource,
+            });
+            actions.setGlobalData({
                 path: (0, utils_1.normalizeUrl)([baseUrl, options.routeBasePath]),
                 versions: versions.map(globalData_1.toGlobalDataVersion),
-                breadcrumbs,
+                breadcrumbs: options.breadcrumbs,
             });
         },
         configureWebpack(_config, isServer, utils, content) {

package/lib/options.js

@@ -21,7 +21,9 @@ exports.DEFAULT_OPTIONS = {
     exclude: utils_1.GlobExcludeDefault,
     sidebarItemsGenerator: generator_1.DefaultSidebarItemsGenerator,
     numberPrefixParser: numberPrefix_1.DefaultNumberPrefixParser,
-    docLayoutComponent: '@theme/DocPage',
+    docsRootComponent: '@theme/DocsRoot',
+    docVersionRootComponent: '@theme/DocVersionRoot',
+    docRootComponent: '@theme/DocRoot',
     docItemComponent: '@theme/DocItem',
     docTagDocListComponent: '@theme/DocTagDocListPage',
     docTagsListComponent: '@theme/DocTagsListPage',
@@ -81,7 +83,9 @@ const OptionsSchema = utils_validation_1.Joi.object({
         then: utils_validation_1.Joi.custom((val) => val ? numberPrefix_1.DefaultNumberPrefixParser : numberPrefix_1.DisabledNumberPrefixParser),
     }))
         .default(() => exports.DEFAULT_OPTIONS.numberPrefixParser),
-    docLayoutComponent: utils_validation_1.Joi.string().default(exports.DEFAULT_OPTIONS.docLayoutComponent),
+    docsRootComponent: utils_validation_1.Joi.string().default(exports.DEFAULT_OPTIONS.docsRootComponent),
+    docVersionRootComponent: utils_validation_1.Joi.string().default(exports.DEFAULT_OPTIONS.docVersionRootComponent),
+    docRootComponent: utils_validation_1.Joi.string().default(exports.DEFAULT_OPTIONS.docRootComponent),
     docItemComponent: utils_validation_1.Joi.string().default(exports.DEFAULT_OPTIONS.docItemComponent),
     docTagsListComponent: utils_validation_1.Joi.string().default(exports.DEFAULT_OPTIONS.docTagsListComponent),
     docTagDocListComponent: utils_validation_1.Joi.string().default(exports.DEFAULT_OPTIONS.docTagDocListComponent),

package/lib/props.d.ts

@@ -4,8 +4,8 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import type { VersionTag } from './types';
-import type { PropSidebars, PropVersionMetadata, PropTagDocList, DocMetadata, LoadedVersion } from '@docusaurus/plugin-content-docs';
+import type { VersionTag, VersionTags } from './types';
+import type { PropSidebars, PropVersionMetadata, PropTagDocList, PropTagsListPage, DocMetadata, LoadedVersion } from '@docusaurus/plugin-content-docs';
 export declare function toSidebarsProp(loadedVersion: LoadedVersion): PropSidebars;
 export declare function toVersionMetadataProp(pluginId: string, loadedVersion: LoadedVersion): PropVersionMetadata;
 export declare function toTagDocListProp({ allTagsPath, tag, docs, }: {
@@ -13,3 +13,4 @@ export declare function toTagDocListProp({ allTagsPath, tag, docs, }: {
     tag: VersionTag;
     docs: DocMetadata[];
 }): PropTagDocList;
+export declare function toTagsListTagsProp(versionTags: VersionTags): PropTagsListPage['tags'];

package/lib/props.js

@@ -6,7 +6,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.toTagDocListProp = exports.toVersionMetadataProp = exports.toSidebarsProp = void 0;
+exports.toTagsListTagsProp = exports.toTagDocListProp = exports.toVersionMetadataProp = exports.toSidebarsProp = void 0;
 const tslib_1 = require("tslib");
 const lodash_1 = tslib_1.__importDefault(require("lodash"));
 const docs_1 = require("./docs");
@@ -127,3 +127,11 @@ function toTagDocListProp({ allTagsPath, tag, docs, }) {
     };
 }
 exports.toTagDocListProp = toTagDocListProp;
+function toTagsListTagsProp(versionTags) {
+    return Object.values(versionTags).map((tagValue) => ({
+        label: tagValue.label,
+        permalink: tagValue.permalink,
+        count: tagValue.docIds.length,
+    }));
+}
+exports.toTagsListTagsProp = toTagsListTagsProp;

package/lib/routes.d.ts

@@ -6,24 +6,17 @@
  */
 import type { PluginContentLoadedActions, RouteConfig } from '@docusaurus/types';
 import type { FullVersion } from './types';
-import type { DocMetadata } from '@docusaurus/plugin-content-docs';
-export declare function createCategoryGeneratedIndexRoutes({ version, actions, docCategoryGeneratedIndexComponent, aliasedSource, }: {
-    version: FullVersion;
+import type { PluginOptions } from '@docusaurus/plugin-content-docs';
+declare type BuildAllRoutesParam = Omit<CreateAllRoutesParam, 'actions'> & {
+    actions: Omit<PluginContentLoadedActions, 'addRoute' | 'setGlobalData'>;
+};
+export declare function buildAllRoutes(param: BuildAllRoutesParam): Promise<RouteConfig[]>;
+declare type CreateAllRoutesParam = {
+    baseUrl: string;
+    versions: FullVersion[];
+    options: PluginOptions;
     actions: PluginContentLoadedActions;
-    docCategoryGeneratedIndexComponent: string;
     aliasedSource: (str: string) => string;
-}): Promise<RouteConfig[]>;
-export declare function createDocRoutes({ docs, actions, docItemComponent, }: {
-    docs: DocMetadata[];
-    actions: PluginContentLoadedActions;
-    docItemComponent: string;
-}): Promise<RouteConfig[]>;
-export declare function createVersionRoutes({ version, actions, docItemComponent, docLayoutComponent, docCategoryGeneratedIndexComponent, pluginId, aliasedSource, }: {
-    version: FullVersion;
-    actions: PluginContentLoadedActions;
-    docLayoutComponent: string;
-    docItemComponent: string;
-    docCategoryGeneratedIndexComponent: string;
-    pluginId: string;
-    aliasedSource: (str: string) => string;
-}): Promise<void>;
+};
+export declare function createAllRoutes(param: CreateAllRoutesParam): Promise<void>;
+export {};

package/lib/routes.js

@@ -6,20 +6,22 @@
  * LICENSE file in the root directory of this source tree.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createVersionRoutes = exports.createDocRoutes = exports.createCategoryGeneratedIndexRoutes = void 0;
+exports.createAllRoutes = exports.buildAllRoutes = void 0;
 const tslib_1 = require("tslib");
+const lodash_1 = tslib_1.__importDefault(require("lodash"));
 const logger_1 = tslib_1.__importDefault(require("@docusaurus/logger"));
 const utils_1 = require("@docusaurus/utils");
 const props_1 = require("./props");
-async function createCategoryGeneratedIndexRoutes({ version, actions, docCategoryGeneratedIndexComponent, aliasedSource, }) {
+const tags_1 = require("./tags");
+async function buildVersionCategoryGeneratedIndexRoutes({ version, actions, options, aliasedSource, }) {
     const slugs = (0, utils_1.createSlugger)();
-    async function createCategoryGeneratedIndexRoute(categoryGeneratedIndex) {
+    async function buildCategoryGeneratedIndexRoute(categoryGeneratedIndex) {
         const { sidebar, ...prop } = categoryGeneratedIndex;
         const propFileName = slugs.slug(`${version.path}-${categoryGeneratedIndex.sidebar}-category-${categoryGeneratedIndex.title}`);
         const propData = await actions.createData(`${(0, utils_1.docuHash)(`category/${propFileName}`)}.json`, JSON.stringify(prop, null, 2));
         return {
             path: categoryGeneratedIndex.permalink,
-            component: docCategoryGeneratedIndexComponent,
+            component: options.docCategoryGeneratedIndexComponent,
             exact: true,
             modules: {
                 categoryGeneratedIndex: aliasedSource(propData),
@@ -29,23 +31,22 @@ async function createCategoryGeneratedIndexRoutes({ version, actions, docCategor
             ...(sidebar && { sidebar }),
         };
     }
-    return Promise.all(version.categoryGeneratedIndices.map(createCategoryGeneratedIndexRoute));
+    return Promise.all(version.categoryGeneratedIndices.map(buildCategoryGeneratedIndexRoute));
 }
-exports.createCategoryGeneratedIndexRoutes = createCategoryGeneratedIndexRoutes;
-async function createDocRoutes({ docs, actions, docItemComponent, }) {
-    return Promise.all(docs.map(async (metadataItem) => {
+async function buildVersionDocRoutes({ version, actions, options, }) {
+    return Promise.all(version.docs.map(async (metadataItem) => {
         await actions.createData(
         // Note that this created data path must be in sync with
         // metadataPath provided to mdx-loader.
         `${(0, utils_1.docuHash)(metadataItem.source)}.json`, JSON.stringify(metadataItem, null, 2));
         const docRoute = {
             path: metadataItem.permalink,
-            component: docItemComponent,
+            component: options.docItemComponent,
             exact: true,
             modules: {
                 content: metadataItem.source,
             },
-            // Because the parent (DocPage) comp need to access it easily
+            // Because the parent (DocRoot) comp need to access it easily
             // This permits to render the sidebar once without unmount/remount when
             // navigating (and preserve sidebar state)
             ...(metadataItem.sidebar && {
@@ -55,42 +56,113 @@ async function createDocRoutes({ docs, actions, docItemComponent, }) {
         return docRoute;
     }));
 }
-exports.createDocRoutes = createDocRoutes;
-async function createVersionRoutes({ version, actions, docItemComponent, docLayoutComponent, docCategoryGeneratedIndexComponent, pluginId, aliasedSource, }) {
-    async function doCreateVersionRoutes() {
-        const versionMetadata = (0, props_1.toVersionMetadataProp)(pluginId, version);
-        const versionMetadataPropPath = await actions.createData(`${(0, utils_1.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,
-                    aliasedSource,
-                }),
-            ]);
-            const routes = [...docRoutes, ...sidebarsRoutes];
-            return routes.sort((a, b) => a.path.localeCompare(b.path));
+async function buildVersionSidebarRoute(param) {
+    const [docRoutes, categoryGeneratedIndexRoutes] = await Promise.all([
+        buildVersionDocRoutes(param),
+        buildVersionCategoryGeneratedIndexRoutes(param),
+    ]);
+    const subRoutes = [...docRoutes, ...categoryGeneratedIndexRoutes];
+    return {
+        path: param.version.path,
+        exact: false,
+        component: param.options.docRootComponent,
+        routes: subRoutes,
+    };
+}
+async function buildVersionTagsRoutes(param) {
+    const { version, options, actions, aliasedSource } = param;
+    const versionTags = (0, tags_1.getVersionTags)(version.docs);
+    async function buildTagsListRoute() {
+        // Don't create a tags list page if there's no tag
+        if (Object.keys(versionTags).length === 0) {
+            return null;
         }
-        actions.addRoute({
+        const tagsProp = (0, props_1.toTagsListTagsProp)(versionTags);
+        const tagsPropPath = await actions.createData(`${(0, utils_1.docuHash)(`tags-list-${version.versionName}-prop`)}.json`, JSON.stringify(tagsProp, null, 2));
+        return {
+            path: version.tagsPath,
+            exact: true,
+            component: options.docTagsListComponent,
+            modules: {
+                tags: aliasedSource(tagsPropPath),
+            },
+        };
+    }
+    async function buildTagDocListRoute(tag) {
+        const tagProps = (0, props_1.toTagDocListProp)({
+            allTagsPath: version.tagsPath,
+            tag,
+            docs: version.docs,
+        });
+        const tagPropPath = await actions.createData(`${(0, utils_1.docuHash)(`tag-${tag.permalink}`)}.json`, JSON.stringify(tagProps, null, 2));
+        return {
+            path: tag.permalink,
+            component: options.docTagDocListComponent,
+            exact: true,
+            modules: {
+                tag: aliasedSource(tagPropPath),
+            },
+        };
+    }
+    const [tagsListRoute, allTagsDocListRoutes] = await Promise.all([
+        buildTagsListRoute(),
+        Promise.all(Object.values(versionTags).map(buildTagDocListRoute)),
+    ]);
+    return lodash_1.default.compact([tagsListRoute, ...allTagsDocListRoutes]);
+}
+async function buildVersionRoutes(param) {
+    const { version, actions, options, aliasedSource } = param;
+    async function buildVersionSubRoutes() {
+        const [sidebarRoute, tagsRoutes] = await Promise.all([
+            buildVersionSidebarRoute(param),
+            buildVersionTagsRoutes(param),
+        ]);
+        return [sidebarRoute, ...tagsRoutes];
+    }
+    async function doBuildVersionRoutes() {
+        const versionProp = (0, props_1.toVersionMetadataProp)(options.id, version);
+        const versionPropPath = await actions.createData(`${(0, utils_1.docuHash)(`version-${version.versionName}-metadata-prop`)}.json`, JSON.stringify(versionProp, null, 2));
+        const subRoutes = await buildVersionSubRoutes();
+        return {
             path: version.path,
-            // Allow matching /docs/* since this is the wrapping route
             exact: false,
-            component: docLayoutComponent,
-            routes: await createVersionSubRoutes(),
+            component: options.docVersionRootComponent,
+            routes: subRoutes,
             modules: {
-                versionMetadata: aliasedSource(versionMetadataPropPath),
+                version: aliasedSource(versionPropPath),
             },
             priority: version.routePriority,
-        });
+        };
     }
     try {
-        return await doCreateVersionRoutes();
+        return await doBuildVersionRoutes();
     }
     catch (err) {
         logger_1.default.error `Can't create version routes for version name=${version.versionName}`;
         throw err;
     }
 }
-exports.createVersionRoutes = createVersionRoutes;
+// TODO we want this buildAllRoutes function to be easily testable
+// Ideally, we should avoid side effects here (ie not injecting actions)
+async function buildAllRoutes(param) {
+    const subRoutes = await Promise.all(param.versions.map((version) => buildVersionRoutes({
+        ...param,
+        version,
+    })));
+    // all docs routes are wrapped under a single parent route, this ensures
+    // the theme layout never unmounts/remounts when navigating between versions
+    return [
+        {
+            path: (0, utils_1.normalizeUrl)([param.baseUrl, param.options.routeBasePath]),
+            exact: false,
+            component: param.options.docsRootComponent,
+            routes: subRoutes,
+        },
+    ];
+}
+exports.buildAllRoutes = buildAllRoutes;
+async function createAllRoutes(param) {
+    const routes = await buildAllRoutes(param);
+    routes.forEach(param.actions.addRoute);
+}
+exports.createAllRoutes = createAllRoutes;

package/lib/versions/index.d.ts

@@ -4,8 +4,9 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import type { PluginOptions, VersionBanner, VersionMetadata } from '@docusaurus/plugin-content-docs';
+import type { FullVersion } from '../types';
 import type { LoadContext } from '@docusaurus/types';
+import type { LoadedVersion, PluginOptions, VersionBanner, VersionMetadata } from '@docusaurus/plugin-content-docs';
 export declare type VersionContext = {
     /** The version name to get banner of. */
     versionName: string;
@@ -35,3 +36,4 @@ export declare function readVersionsMetadata({ context, options, }: {
     context: LoadContext;
     options: PluginOptions;
 }): Promise<VersionMetadata[]>;
+export declare function toFullVersion(version: LoadedVersion): FullVersion;

package/lib/versions/index.js

@@ -6,13 +6,15 @@
  * LICENSE file in the root directory of this source tree.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.readVersionsMetadata = exports.filterVersions = exports.getVersionNoIndex = exports.getVersionBadge = exports.getVersionBanner = exports.getDefaultVersionBanner = void 0;
+exports.toFullVersion = exports.readVersionsMetadata = exports.filterVersions = exports.getVersionNoIndex = exports.getVersionBadge = exports.getVersionBanner = exports.getDefaultVersionBanner = void 0;
 const tslib_1 = require("tslib");
 const path_1 = tslib_1.__importDefault(require("path"));
 const utils_1 = require("@docusaurus/utils");
 const constants_1 = require("../constants");
 const validation_1 = require("./validation");
 const files_1 = require("./files");
+const utils_2 = require("../sidebars/utils");
+const categoryGeneratedIndex_1 = require("../categoryGeneratedIndex");
 function getVersionEditUrls({ contentPath, contentPathLocalized, context, options, }) {
     // If the user is using the functional form of editUrl,
     // she has total freedom and we can't compute a "version edit url"
@@ -157,3 +159,15 @@ async function readVersionsMetadata({ context, options, }) {
     return versionsMetadata;
 }
 exports.readVersionsMetadata = readVersionsMetadata;
+function toFullVersion(version) {
+    const sidebarsUtils = (0, utils_2.createSidebarsUtils)(version.sidebars);
+    return {
+        ...version,
+        sidebarsUtils,
+        categoryGeneratedIndices: (0, categoryGeneratedIndex_1.getCategoryGeneratedIndexMetadataList)({
+            docs: version.docs,
+            sidebarsUtils,
+        }),
+    };
+}
+exports.toFullVersion = toFullVersion;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/plugin-content-docs",
-  "version": "0.0.0-5264",
+  "version": "0.0.0-5265",
   "description": "Docs plugin for Docusaurus.",
   "main": "lib/index.js",
   "sideEffects": false,
@@ -35,13 +35,13 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/core": "0.0.0-5264",
-    "@docusaurus/logger": "0.0.0-5264",
-    "@docusaurus/mdx-loader": "0.0.0-5264",
-    "@docusaurus/module-type-aliases": "0.0.0-5264",
-    "@docusaurus/types": "0.0.0-5264",
-    "@docusaurus/utils": "0.0.0-5264",
-    "@docusaurus/utils-validation": "0.0.0-5264",
+    "@docusaurus/core": "0.0.0-5265",
+    "@docusaurus/logger": "0.0.0-5265",
+    "@docusaurus/mdx-loader": "0.0.0-5265",
+    "@docusaurus/module-type-aliases": "0.0.0-5265",
+    "@docusaurus/types": "0.0.0-5265",
+    "@docusaurus/utils": "0.0.0-5265",
+    "@docusaurus/utils-validation": "0.0.0-5265",
     "@types/react-router-config": "^5.0.6",
     "combine-promises": "^1.1.0",
     "fs-extra": "^10.1.0",
@@ -67,5 +67,5 @@
   "engines": {
     "node": ">=16.14"
   },
-  "gitHead": "4b2d0fc902b4ab1fcede0f6df98c45f060a4fbfc"
+  "gitHead": "ac59d7c969c795c2163c8e8843c11d94e210f87f"
 }

package/src/index.ts

@@ -27,22 +27,18 @@ import {
   addDocNavigation,
   type DocEnv,
 } from './docs';
-import {readVersionsMetadata} from './versions';
+import {readVersionsMetadata, toFullVersion} from './versions';
 import {cliDocsVersionCommand} from './cli';
 import {VERSIONS_JSON_FILE} from './constants';
 import {toGlobalDataVersion} from './globalData';
-import {toTagDocListProp} from './props';
-import {getCategoryGeneratedIndexMetadataList} from './categoryGeneratedIndex';
 import {
   translateLoadedContent,
   getLoadedContentTranslationFiles,
 } from './translations';
-import {getVersionTags} from './tags';
-import {createVersionRoutes} from './routes';
+import {createAllRoutes} from './routes';
 import {createSidebarsUtils} from './sidebars/utils';
 
 import type {
-  PropTagsListPage,
   PluginOptions,
   DocMetadataBase,
   VersionMetadata,
@@ -55,7 +51,6 @@ import type {
   SourceToPermalink,
   DocFile,
   DocsMarkdownOption,
-  VersionTag,
   FullVersion,
 } from './types';
 import type {RuleSetRule} from 'webpack';
@@ -209,102 +204,20 @@ export default async function pluginContentDocs(
     },
 
     async contentLoaded({content, actions}) {
-      const {loadedVersions} = content;
-      const {
-        docLayoutComponent,
-        docItemComponent,
-        docCategoryGeneratedIndexComponent,
-        breadcrumbs,
-      } = options;
-      const {addRoute, createData, setGlobalData} = actions;
-      const versions: FullVersion[] = loadedVersions.map((version) => {
-        const sidebarsUtils = createSidebarsUtils(version.sidebars);
-        return {
-          ...version,
-          sidebarsUtils,
-          categoryGeneratedIndices: getCategoryGeneratedIndexMetadataList({
-            docs: version.docs,
-            sidebarsUtils,
-          }),
-        };
+      const versions: FullVersion[] = content.loadedVersions.map(toFullVersion);
+
+      await createAllRoutes({
+        baseUrl,
+        versions,
+        options,
+        actions,
+        aliasedSource,
       });
 
-      async function createVersionTagsRoutes(version: FullVersion) {
-        const versionTags = getVersionTags(version.docs);
-
-        // TODO tags should be a sub route of the version route
-        async function createTagsListPage() {
-          const tagsProp: PropTagsListPage['tags'] = Object.values(
-            versionTags,
-          ).map((tagValue) => ({
-            label: tagValue.label,
-            permalink: tagValue.permalink,
-            count: tagValue.docIds.length,
-          }));
-
-          // Only create /tags page if there are tags.
-          if (tagsProp.length > 0) {
-            const tagsPropPath = await createData(
-              `${docuHash(`tags-list-${version.versionName}-prop`)}.json`,
-              JSON.stringify(tagsProp, null, 2),
-            );
-            addRoute({
-              path: version.tagsPath,
-              exact: true,
-              component: options.docTagsListComponent,
-              modules: {
-                tags: aliasedSource(tagsPropPath),
-              },
-            });
-          }
-        }
-
-        // TODO tags should be a sub route of the version route
-        async function createTagDocListPage(tag: VersionTag) {
-          const tagProps = toTagDocListProp({
-            allTagsPath: version.tagsPath,
-            tag,
-            docs: version.docs,
-          });
-          const tagPropPath = await createData(
-            `${docuHash(`tag-${tag.permalink}`)}.json`,
-            JSON.stringify(tagProps, null, 2),
-          );
-          addRoute({
-            path: tag.permalink,
-            component: options.docTagDocListComponent,
-            exact: true,
-            modules: {
-              tag: aliasedSource(tagPropPath),
-            },
-          });
-        }
-
-        await createTagsListPage();
-        await Promise.all(Object.values(versionTags).map(createTagDocListPage));
-      }
-
-      await Promise.all(
-        versions.map((version) =>
-          createVersionRoutes({
-            version,
-            docItemComponent,
-            docLayoutComponent,
-            docCategoryGeneratedIndexComponent,
-            pluginId,
-            aliasedSource,
-            actions,
-          }),
-        ),
-      );
-
-      // TODO tags should be a sub route of the version route
-      await Promise.all(versions.map(createVersionTagsRoutes));
-
-      setGlobalData({
+      actions.setGlobalData({
         path: normalizeUrl([baseUrl, options.routeBasePath]),
         versions: versions.map(toGlobalDataVersion),
-        breadcrumbs,
+        breadcrumbs: options.breadcrumbs,
       });
     },
 

package/src/options.ts

@@ -30,7 +30,9 @@ export const DEFAULT_OPTIONS: Omit<PluginOptions, 'id' | 'sidebarPath'> = {
   exclude: GlobExcludeDefault,
   sidebarItemsGenerator: DefaultSidebarItemsGenerator,
   numberPrefixParser: DefaultNumberPrefixParser,
-  docLayoutComponent: '@theme/DocPage',
+  docsRootComponent: '@theme/DocsRoot',
+  docVersionRootComponent: '@theme/DocVersionRoot',
+  docRootComponent: '@theme/DocRoot',
   docItemComponent: '@theme/DocItem',
   docTagDocListComponent: '@theme/DocTagDocListPage',
   docTagsListComponent: '@theme/DocTagsListPage',
@@ -104,7 +106,11 @@ const OptionsSchema = Joi.object<PluginOptions>({
       }),
     )
     .default(() => DEFAULT_OPTIONS.numberPrefixParser),
-  docLayoutComponent: Joi.string().default(DEFAULT_OPTIONS.docLayoutComponent),
+  docsRootComponent: Joi.string().default(DEFAULT_OPTIONS.docsRootComponent),
+  docVersionRootComponent: Joi.string().default(
+    DEFAULT_OPTIONS.docVersionRootComponent,
+  ),
+  docRootComponent: Joi.string().default(DEFAULT_OPTIONS.docRootComponent),
   docItemComponent: Joi.string().default(DEFAULT_OPTIONS.docItemComponent),
   docTagsListComponent: Joi.string().default(
     DEFAULT_OPTIONS.docTagsListComponent,

package/src/plugin-content-docs.d.ts

@@ -198,10 +198,24 @@ declare module '@docusaurus/plugin-content-docs' {
        */
       exclude: string[];
       /**
-       * Root layout component of each doc page. Provides the version data
-       * context, and is not unmounted when switching docs.
+       * Parent component of all the docs plugin pages (including all versions).
+       * Stays mounted when navigation between docs pages and versions.
        */
-      docLayoutComponent: string;
+      docsRootComponent: string;
+      /**
+       * Parent component of all docs pages of an individual version:
+       * - docs pages with sidebars
+       * - tags pages
+       * Stays mounted when navigation between pages of that specific version.
+       */
+      docVersionRootComponent: string;
+      /**
+       * Parent component of all docs pages with sidebars:
+       * - regular docs pages
+       * - category generated index pages
+       * Stays mounted when navigation between such pages.
+       */
+      docRootComponent: string;
       /** Main doc container, with TOC, pagination, etc. */
       docItemComponent: string;
       /** Root component of the "docs containing tag X" page. */
@@ -610,14 +624,32 @@ declare module '@theme/DocBreadcrumbs' {
   export default function DocBreadcrumbs(): JSX.Element;
 }
 
-declare module '@theme/DocPage' {
+declare module '@theme/DocsRoot' {
+  import type {RouteConfigComponentProps} from 'react-router-config';
+  import type {Required} from 'utility-types';
+
+  export interface Props extends Required<RouteConfigComponentProps, 'route'> {}
+
+  export default function DocsRoot(props: Props): JSX.Element;
+}
+
+declare module '@theme/DocVersionRoot' {
   import type {PropVersionMetadata} from '@docusaurus/plugin-content-docs';
   import type {RouteConfigComponentProps} from 'react-router-config';
   import type {Required} from 'utility-types';
 
   export interface Props extends Required<RouteConfigComponentProps, 'route'> {
-    readonly versionMetadata: PropVersionMetadata;
+    readonly version: PropVersionMetadata;
   }
 
-  export default function DocPage(props: Props): JSX.Element;
+  export default function DocVersionRoot(props: Props): JSX.Element;
+}
+
+declare module '@theme/DocRoot' {
+  import type {RouteConfigComponentProps} from 'react-router-config';
+  import type {Required} from 'utility-types';
+
+  export interface Props extends Required<RouteConfigComponentProps, 'route'> {}
+
+  export default function DocRoot(props: Props): JSX.Element;
 }

package/src/props.ts

@@ -7,7 +7,7 @@
 
 import _ from 'lodash';
 import {createDocsByIdIndex} from './docs';
-import type {VersionTag} from './types';
+import type {VersionTag, VersionTags} from './types';
 import type {
   SidebarItemDoc,
   SidebarItem,
@@ -21,6 +21,7 @@ import type {
   PropSidebarItemCategory,
   PropTagDocList,
   PropTagDocListDoc,
+  PropTagsListPage,
   PropSidebarItemLink,
   PropVersionDocs,
   DocMetadata,
@@ -181,3 +182,13 @@ export function toTagDocListProp({
     items: toDocListProp(),
   };
 }
+
+export function toTagsListTagsProp(
+  versionTags: VersionTags,
+): PropTagsListPage['tags'] {
+  return Object.values(versionTags).map((tagValue) => ({
+    label: tagValue.label,
+    permalink: tagValue.permalink,
+    count: tagValue.docIds.length,
+  }));
+}

package/src/routes.ts

@@ -5,30 +5,32 @@
  * LICENSE file in the root directory of this source tree.
  */
 
+import _ from 'lodash';
 import logger from '@docusaurus/logger';
-import {docuHash, createSlugger} from '@docusaurus/utils';
-import {toVersionMetadataProp} from './props';
+import {docuHash, createSlugger, normalizeUrl} from '@docusaurus/utils';
+import {
+  toTagDocListProp,
+  toTagsListTagsProp,
+  toVersionMetadataProp,
+} from './props';
+import {getVersionTags} from './tags';
 import type {PluginContentLoadedActions, RouteConfig} from '@docusaurus/types';
-import type {FullVersion} from './types';
+import type {FullVersion, VersionTag} from './types';
 import type {
   CategoryGeneratedIndexMetadata,
-  DocMetadata,
+  PluginOptions,
+  PropTagsListPage,
 } from '@docusaurus/plugin-content-docs';
 
-export async function createCategoryGeneratedIndexRoutes({
+async function buildVersionCategoryGeneratedIndexRoutes({
   version,
   actions,
-  docCategoryGeneratedIndexComponent,
+  options,
   aliasedSource,
-}: {
-  version: FullVersion;
-  actions: PluginContentLoadedActions;
-  docCategoryGeneratedIndexComponent: string;
-  aliasedSource: (str: string) => string;
-}): Promise<RouteConfig[]> {
+}: BuildVersionRoutesParam): Promise<RouteConfig[]> {
   const slugs = createSlugger();
 
-  async function createCategoryGeneratedIndexRoute(
+  async function buildCategoryGeneratedIndexRoute(
     categoryGeneratedIndex: CategoryGeneratedIndexMetadata,
   ): Promise<RouteConfig> {
     const {sidebar, ...prop} = categoryGeneratedIndex;
@@ -44,7 +46,7 @@ export async function createCategoryGeneratedIndexRoutes({
 
     return {
       path: categoryGeneratedIndex.permalink,
-      component: docCategoryGeneratedIndexComponent,
+      component: options.docCategoryGeneratedIndexComponent,
       exact: true,
       modules: {
         categoryGeneratedIndex: aliasedSource(propData),
@@ -56,21 +58,17 @@ export async function createCategoryGeneratedIndexRoutes({
   }
 
   return Promise.all(
-    version.categoryGeneratedIndices.map(createCategoryGeneratedIndexRoute),
+    version.categoryGeneratedIndices.map(buildCategoryGeneratedIndexRoute),
   );
 }
 
-export async function createDocRoutes({
-  docs,
+async function buildVersionDocRoutes({
+  version,
   actions,
-  docItemComponent,
-}: {
-  docs: DocMetadata[];
-  actions: PluginContentLoadedActions;
-  docItemComponent: string;
-}): Promise<RouteConfig[]> {
+  options,
+}: BuildVersionRoutesParam): Promise<RouteConfig[]> {
   return Promise.all(
-    docs.map(async (metadataItem) => {
+    version.docs.map(async (metadataItem) => {
       await actions.createData(
         // Note that this created data path must be in sync with
         // metadataPath provided to mdx-loader.
@@ -80,12 +78,12 @@ export async function createDocRoutes({
 
       const docRoute: RouteConfig = {
         path: metadataItem.permalink,
-        component: docItemComponent,
+        component: options.docItemComponent,
         exact: true,
         modules: {
           content: metadataItem.source,
         },
-        // Because the parent (DocPage) comp need to access it easily
+        // Because the parent (DocRoot) comp need to access it easily
         // This permits to render the sidebar once without unmount/remount when
         // navigating (and preserve sidebar state)
         ...(metadataItem.sidebar && {
@@ -98,62 +96,160 @@ export async function createDocRoutes({
   );
 }
 
-export async function createVersionRoutes({
-  version,
-  actions,
-  docItemComponent,
-  docLayoutComponent,
-  docCategoryGeneratedIndexComponent,
-  pluginId,
-  aliasedSource,
-}: {
-  version: FullVersion;
-  actions: PluginContentLoadedActions;
-  docLayoutComponent: string;
-  docItemComponent: string;
-  docCategoryGeneratedIndexComponent: string;
-  pluginId: string;
-  aliasedSource: (str: string) => string;
-}): Promise<void> {
-  async function doCreateVersionRoutes(): 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 buildVersionSidebarRoute(param: BuildVersionRoutesParam) {
+  const [docRoutes, categoryGeneratedIndexRoutes] = await Promise.all([
+    buildVersionDocRoutes(param),
+    buildVersionCategoryGeneratedIndexRoutes(param),
+  ]);
+  const subRoutes = [...docRoutes, ...categoryGeneratedIndexRoutes];
+  return {
+    path: param.version.path,
+    exact: false,
+    component: param.options.docRootComponent,
+    routes: subRoutes,
+  };
+}
 
-    async function createVersionSubRoutes() {
-      const [docRoutes, sidebarsRoutes] = await Promise.all([
-        createDocRoutes({docs: version.docs, actions, docItemComponent}),
-        createCategoryGeneratedIndexRoutes({
-          version,
-          actions,
-          docCategoryGeneratedIndexComponent,
-          aliasedSource,
-        }),
-      ]);
+async function buildVersionTagsRoutes(
+  param: BuildVersionRoutesParam,
+): Promise<RouteConfig[]> {
+  const {version, options, actions, aliasedSource} = param;
+  const versionTags = getVersionTags(version.docs);
 
-      const routes = [...docRoutes, ...sidebarsRoutes];
-      return routes.sort((a, b) => a.path.localeCompare(b.path));
+  async function buildTagsListRoute(): Promise<RouteConfig | null> {
+    // Don't create a tags list page if there's no tag
+    if (Object.keys(versionTags).length === 0) {
+      return null;
     }
+    const tagsProp: PropTagsListPage['tags'] = toTagsListTagsProp(versionTags);
+    const tagsPropPath = await actions.createData(
+      `${docuHash(`tags-list-${version.versionName}-prop`)}.json`,
+      JSON.stringify(tagsProp, null, 2),
+    );
+    return {
+      path: version.tagsPath,
+      exact: true,
+      component: options.docTagsListComponent,
+      modules: {
+        tags: aliasedSource(tagsPropPath),
+      },
+    };
+  }
+
+  async function buildTagDocListRoute(tag: VersionTag): Promise<RouteConfig> {
+    const tagProps = toTagDocListProp({
+      allTagsPath: version.tagsPath,
+      tag,
+      docs: version.docs,
+    });
+    const tagPropPath = await actions.createData(
+      `${docuHash(`tag-${tag.permalink}`)}.json`,
+      JSON.stringify(tagProps, null, 2),
+    );
+    return {
+      path: tag.permalink,
+      component: options.docTagDocListComponent,
+      exact: true,
+      modules: {
+        tag: aliasedSource(tagPropPath),
+      },
+    };
+  }
+
+  const [tagsListRoute, allTagsDocListRoutes] = await Promise.all([
+    buildTagsListRoute(),
+    Promise.all(Object.values(versionTags).map(buildTagDocListRoute)),
+  ]);
+
+  return _.compact([tagsListRoute, ...allTagsDocListRoutes]);
+}
+
+type BuildVersionRoutesParam = Omit<BuildAllRoutesParam, 'versions'> & {
+  version: FullVersion;
+};
+
+async function buildVersionRoutes(
+  param: BuildVersionRoutesParam,
+): Promise<RouteConfig> {
+  const {version, actions, options, aliasedSource} = param;
 
-    actions.addRoute({
+  async function buildVersionSubRoutes() {
+    const [sidebarRoute, tagsRoutes] = await Promise.all([
+      buildVersionSidebarRoute(param),
+      buildVersionTagsRoutes(param),
+    ]);
+
+    return [sidebarRoute, ...tagsRoutes];
+  }
+
+  async function doBuildVersionRoutes(): Promise<RouteConfig> {
+    const versionProp = toVersionMetadataProp(options.id, version);
+    const versionPropPath = await actions.createData(
+      `${docuHash(`version-${version.versionName}-metadata-prop`)}.json`,
+      JSON.stringify(versionProp, null, 2),
+    );
+    const subRoutes = await buildVersionSubRoutes();
+    return {
       path: version.path,
-      // Allow matching /docs/* since this is the wrapping route
       exact: false,
-      component: docLayoutComponent,
-      routes: await createVersionSubRoutes(),
+      component: options.docVersionRootComponent,
+      routes: subRoutes,
       modules: {
-        versionMetadata: aliasedSource(versionMetadataPropPath),
+        version: aliasedSource(versionPropPath),
       },
       priority: version.routePriority,
-    });
+    };
   }
 
   try {
-    return await doCreateVersionRoutes();
+    return await doBuildVersionRoutes();
   } catch (err) {
     logger.error`Can't create version routes for version name=${version.versionName}`;
     throw err;
   }
 }
+
+type BuildAllRoutesParam = Omit<CreateAllRoutesParam, 'actions'> & {
+  actions: Omit<PluginContentLoadedActions, 'addRoute' | 'setGlobalData'>;
+};
+
+// TODO we want this buildAllRoutes function to be easily testable
+// Ideally, we should avoid side effects here (ie not injecting actions)
+export async function buildAllRoutes(
+  param: BuildAllRoutesParam,
+): Promise<RouteConfig[]> {
+  const subRoutes = await Promise.all(
+    param.versions.map((version) =>
+      buildVersionRoutes({
+        ...param,
+        version,
+      }),
+    ),
+  );
+
+  // all docs routes are wrapped under a single parent route, this ensures
+  // the theme layout never unmounts/remounts when navigating between versions
+  return [
+    {
+      path: normalizeUrl([param.baseUrl, param.options.routeBasePath]),
+      exact: false,
+      component: param.options.docsRootComponent,
+      routes: subRoutes,
+    },
+  ];
+}
+
+type CreateAllRoutesParam = {
+  baseUrl: string;
+  versions: FullVersion[];
+  options: PluginOptions;
+  actions: PluginContentLoadedActions;
+  aliasedSource: (str: string) => string;
+};
+
+export async function createAllRoutes(
+  param: CreateAllRoutesParam,
+): Promise<void> {
+  const routes = await buildAllRoutes(param);
+  routes.forEach(param.actions.addRoute);
+}

package/src/versions/index.ts

@@ -14,12 +14,16 @@ import {
   getVersionMetadataPaths,
   readVersionNames,
 } from './files';
+import {createSidebarsUtils} from '../sidebars/utils';
+import {getCategoryGeneratedIndexMetadataList} from '../categoryGeneratedIndex';
+import type {FullVersion} from '../types';
+import type {LoadContext} from '@docusaurus/types';
 import type {
+  LoadedVersion,
   PluginOptions,
   VersionBanner,
   VersionMetadata,
 } from '@docusaurus/plugin-content-docs';
-import type {LoadContext} from '@docusaurus/types';
 
 export type VersionContext = {
   /** The version name to get banner of. */
@@ -252,3 +256,15 @@ export async function readVersionsMetadata({
   );
   return versionsMetadata;
 }
+
+export function toFullVersion(version: LoadedVersion): FullVersion {
+  const sidebarsUtils = createSidebarsUtils(version.sidebars);
+  return {
+    ...version,
+    sidebarsUtils,
+    categoryGeneratedIndices: getCategoryGeneratedIndexMetadataList({
+      docs: version.docs,
+      sidebarsUtils,
+    }),
+  };
+}