@docusaurus/plugin-content-docs 2.0.0-beta.8e9b829d9 → 2.0.0-beta.9

package/src/__tests__/versions.test.ts

@@ -77,10 +77,13 @@ describe('simple site', () => {
       isLast: true,
       routePriority: -1,
       sidebarFilePath: undefined,
+      tagsPath: '/docs/tags',
       versionLabel: 'Next',
       versionName: 'current',
       versionPath: '/docs',
-      versionBanner: 'none',
+      versionBanner: null,
+      versionBadge: false,
+      versionClassName: 'docs-version-current',
     };
     return {simpleSiteDir, defaultOptions, defaultContext, vCurrent};
   }
@@ -111,6 +114,7 @@ describe('simple site', () => {
       {
         ...vCurrent,
         versionPath: '/myBaseUrl/docs',
+        tagsPath: '/myBaseUrl/docs/tags',
       },
     ]);
   });
@@ -141,6 +145,7 @@ describe('simple site', () => {
         versionLabel: 'current-label',
         routePriority: undefined,
         sidebarFilePath: undefined,
+        tagsPath: '/myBaseUrl/docs/current-path/tags',
         versionEditUrl: undefined,
         versionEditUrlLocalized: undefined,
       },
@@ -232,10 +237,13 @@ describe('versioned site, pluginId=default', () => {
       isLast: false,
       routePriority: undefined,
       sidebarFilePath: path.join(versionedSiteDir, 'sidebars.json'),
+      tagsPath: '/docs/next/tags',
       versionLabel: 'Next',
       versionName: 'current',
       versionPath: '/docs/next',
       versionBanner: 'unreleased',
+      versionBadge: true,
+      versionClassName: 'docs-version-current',
     };
 
     const v101: VersionMetadata = {
@@ -250,10 +258,13 @@ describe('versioned site, pluginId=default', () => {
         versionedSiteDir,
         'versioned_sidebars/version-1.0.1-sidebars.json',
       ),
+      tagsPath: '/docs/tags',
       versionLabel: '1.0.1',
       versionName: '1.0.1',
       versionPath: '/docs',
-      versionBanner: 'none',
+      versionBanner: null,
+      versionBadge: true,
+      versionClassName: 'docs-version-1.0.1',
     };
 
     const v100: VersionMetadata = {
@@ -268,10 +279,13 @@ describe('versioned site, pluginId=default', () => {
         versionedSiteDir,
         'versioned_sidebars/version-1.0.0-sidebars.json',
       ),
+      tagsPath: '/docs/1.0.0/tags',
       versionLabel: '1.0.0',
       versionName: '1.0.0',
       versionPath: '/docs/1.0.0',
       versionBanner: 'unmaintained',
+      versionBadge: true,
+      versionClassName: 'docs-version-1.0.0',
     };
 
     const vwithSlugs: VersionMetadata = {
@@ -289,10 +303,13 @@ describe('versioned site, pluginId=default', () => {
         versionedSiteDir,
         'versioned_sidebars/version-withSlugs-sidebars.json',
       ),
+      tagsPath: '/docs/withSlugs/tags',
       versionLabel: 'withSlugs',
       versionName: 'withSlugs',
       versionPath: '/docs/withSlugs',
       versionBanner: 'unmaintained',
+      versionBadge: true,
+      versionClassName: 'docs-version-withSlugs',
     };
 
     return {
@@ -307,14 +324,8 @@ describe('versioned site, pluginId=default', () => {
   }
 
   test('readVersionsMetadata versioned site', async () => {
-    const {
-      defaultOptions,
-      defaultContext,
-      vCurrent,
-      v101,
-      v100,
-      vwithSlugs,
-    } = await loadSite();
+    const {defaultOptions, defaultContext, vCurrent, v101, v100, vwithSlugs} =
+      await loadSite();
 
     const versionsMetadata = readVersionsMetadata({
       options: defaultOptions,
@@ -325,13 +336,8 @@ describe('versioned site, pluginId=default', () => {
   });
 
   test('readVersionsMetadata versioned site with includeCurrentVersion=false', async () => {
-    const {
-      defaultOptions,
-      defaultContext,
-      v101,
-      v100,
-      vwithSlugs,
-    } = await loadSite();
+    const {defaultOptions, defaultContext, v101, v100, vwithSlugs} =
+      await loadSite();
 
     const versionsMetadata = readVersionsMetadata({
       options: {...defaultOptions, includeCurrentVersion: false},
@@ -347,14 +353,8 @@ describe('versioned site, pluginId=default', () => {
   });
 
   test('readVersionsMetadata versioned site with version options', async () => {
-    const {
-      defaultOptions,
-      defaultContext,
-      vCurrent,
-      v101,
-      v100,
-      vwithSlugs,
-    } = await loadSite();
+    const {defaultOptions, defaultContext, vCurrent, v101, v100, vwithSlugs} =
+      await loadSite();
 
     const versionsMetadata = readVersionsMetadata({
       options: {
@@ -364,6 +364,8 @@ describe('versioned site, pluginId=default', () => {
           current: {
             path: 'current-path',
             banner: 'unmaintained',
+            badge: false,
+            className: 'custom-current-className',
           },
           '1.0.0': {
             label: '1.0.0-label',
@@ -377,13 +379,17 @@ describe('versioned site, pluginId=default', () => {
     expect(versionsMetadata).toEqual([
       {
         ...vCurrent,
+        tagsPath: '/docs/current-path/tags',
         versionPath: '/docs/current-path',
         versionBanner: 'unmaintained',
+        versionBadge: false,
+        versionClassName: 'custom-current-className',
       },
       {
         ...v101,
         isLast: false,
         routePriority: undefined,
+        tagsPath: '/docs/1.0.1/tags',
         versionPath: '/docs/1.0.1',
         versionBanner: 'unreleased',
       },
@@ -391,6 +397,7 @@ describe('versioned site, pluginId=default', () => {
         ...v100,
         isLast: true,
         routePriority: -1,
+        tagsPath: '/docs/tags',
         versionLabel: '1.0.0-label',
         versionPath: '/docs',
         versionBanner: 'unreleased',
@@ -400,19 +407,13 @@ describe('versioned site, pluginId=default', () => {
   });
 
   test('readVersionsMetadata versioned site with editUrl', async () => {
-    const {
-      defaultOptions,
-      defaultContext,
-      vCurrent,
-      v101,
-      v100,
-      vwithSlugs,
-    } = await loadSite();
+    const {defaultOptions, defaultContext, vCurrent, v101, v100, vwithSlugs} =
+      await loadSite();
 
     const versionsMetadata = readVersionsMetadata({
       options: {
         ...defaultOptions,
-        editUrl: 'https://github.com/facebook/docusaurus/edit/master/website/',
+        editUrl: 'https://github.com/facebook/docusaurus/edit/main/website/',
       },
       context: defaultContext,
     });
@@ -421,48 +422,42 @@ describe('versioned site, pluginId=default', () => {
       {
         ...vCurrent,
         versionEditUrl:
-          'https://github.com/facebook/docusaurus/edit/master/website/docs',
+          'https://github.com/facebook/docusaurus/edit/main/website/docs',
         versionEditUrlLocalized:
-          'https://github.com/facebook/docusaurus/edit/master/website/i18n/en/docusaurus-plugin-content-docs/current',
+          'https://github.com/facebook/docusaurus/edit/main/website/i18n/en/docusaurus-plugin-content-docs/current',
       },
       {
         ...v101,
         versionEditUrl:
-          'https://github.com/facebook/docusaurus/edit/master/website/versioned_docs/version-1.0.1',
+          'https://github.com/facebook/docusaurus/edit/main/website/versioned_docs/version-1.0.1',
         versionEditUrlLocalized:
-          'https://github.com/facebook/docusaurus/edit/master/website/i18n/en/docusaurus-plugin-content-docs/version-1.0.1',
+          'https://github.com/facebook/docusaurus/edit/main/website/i18n/en/docusaurus-plugin-content-docs/version-1.0.1',
       },
       {
         ...v100,
         versionEditUrl:
-          'https://github.com/facebook/docusaurus/edit/master/website/versioned_docs/version-1.0.0',
+          'https://github.com/facebook/docusaurus/edit/main/website/versioned_docs/version-1.0.0',
         versionEditUrlLocalized:
-          'https://github.com/facebook/docusaurus/edit/master/website/i18n/en/docusaurus-plugin-content-docs/version-1.0.0',
+          'https://github.com/facebook/docusaurus/edit/main/website/i18n/en/docusaurus-plugin-content-docs/version-1.0.0',
       },
       {
         ...vwithSlugs,
         versionEditUrl:
-          'https://github.com/facebook/docusaurus/edit/master/website/versioned_docs/version-withSlugs',
+          'https://github.com/facebook/docusaurus/edit/main/website/versioned_docs/version-withSlugs',
         versionEditUrlLocalized:
-          'https://github.com/facebook/docusaurus/edit/master/website/i18n/en/docusaurus-plugin-content-docs/version-withSlugs',
+          'https://github.com/facebook/docusaurus/edit/main/website/i18n/en/docusaurus-plugin-content-docs/version-withSlugs',
       },
     ]);
   });
 
   test('readVersionsMetadata versioned site with editUrl and editCurrentVersion=true', async () => {
-    const {
-      defaultOptions,
-      defaultContext,
-      vCurrent,
-      v101,
-      v100,
-      vwithSlugs,
-    } = await loadSite();
+    const {defaultOptions, defaultContext, vCurrent, v101, v100, vwithSlugs} =
+      await loadSite();
 
     const versionsMetadata = readVersionsMetadata({
       options: {
         ...defaultOptions,
-        editUrl: 'https://github.com/facebook/docusaurus/edit/master/website/',
+        editUrl: 'https://github.com/facebook/docusaurus/edit/main/website/',
         editCurrentVersion: true,
       },
       context: defaultContext,
@@ -472,30 +467,30 @@ describe('versioned site, pluginId=default', () => {
       {
         ...vCurrent,
         versionEditUrl:
-          'https://github.com/facebook/docusaurus/edit/master/website/docs',
+          'https://github.com/facebook/docusaurus/edit/main/website/docs',
         versionEditUrlLocalized:
-          'https://github.com/facebook/docusaurus/edit/master/website/i18n/en/docusaurus-plugin-content-docs/current',
+          'https://github.com/facebook/docusaurus/edit/main/website/i18n/en/docusaurus-plugin-content-docs/current',
       },
       {
         ...v101,
         versionEditUrl:
-          'https://github.com/facebook/docusaurus/edit/master/website/docs',
+          'https://github.com/facebook/docusaurus/edit/main/website/docs',
         versionEditUrlLocalized:
-          'https://github.com/facebook/docusaurus/edit/master/website/i18n/en/docusaurus-plugin-content-docs/current',
+          'https://github.com/facebook/docusaurus/edit/main/website/i18n/en/docusaurus-plugin-content-docs/current',
       },
       {
         ...v100,
         versionEditUrl:
-          'https://github.com/facebook/docusaurus/edit/master/website/docs',
+          'https://github.com/facebook/docusaurus/edit/main/website/docs',
         versionEditUrlLocalized:
-          'https://github.com/facebook/docusaurus/edit/master/website/i18n/en/docusaurus-plugin-content-docs/current',
+          'https://github.com/facebook/docusaurus/edit/main/website/i18n/en/docusaurus-plugin-content-docs/current',
       },
       {
         ...vwithSlugs,
         versionEditUrl:
-          'https://github.com/facebook/docusaurus/edit/master/website/docs',
+          'https://github.com/facebook/docusaurus/edit/main/website/docs',
         versionEditUrlLocalized:
-          'https://github.com/facebook/docusaurus/edit/master/website/i18n/en/docusaurus-plugin-content-docs/current',
+          'https://github.com/facebook/docusaurus/edit/main/website/i18n/en/docusaurus-plugin-content-docs/current',
       },
     ]);
   });
@@ -528,8 +523,10 @@ describe('versioned site, pluginId=default', () => {
         ...vCurrent,
         isLast: true,
         routePriority: -1,
+        tagsPath: '/docs/tags',
         versionPath: '/docs',
-        versionBanner: 'none',
+        versionBanner: null,
+        versionBadge: false,
       },
     ]);
   });
@@ -648,10 +645,13 @@ describe('versioned site, pluginId=community', () => {
       isLast: false,
       routePriority: undefined,
       sidebarFilePath: path.join(versionedSiteDir, 'sidebars.json'),
+      tagsPath: '/communityBasePath/next/tags',
       versionLabel: 'Next',
       versionName: 'current',
       versionPath: '/communityBasePath/next',
       versionBanner: 'unreleased',
+      versionBadge: true,
+      versionClassName: 'docs-version-current',
     };
 
     const v100: VersionMetadata = {
@@ -669,10 +669,13 @@ describe('versioned site, pluginId=community', () => {
         versionedSiteDir,
         'community_versioned_sidebars/version-1.0.0-sidebars.json',
       ),
+      tagsPath: '/communityBasePath/tags',
       versionLabel: '1.0.0',
       versionName: '1.0.0',
       versionPath: '/communityBasePath',
-      versionBanner: 'none',
+      versionBanner: null,
+      versionBadge: true,
+      versionClassName: 'docs-version-1.0.0',
     };
 
     return {versionedSiteDir, defaultOptions, defaultContext, vCurrent, v100};
@@ -699,7 +702,7 @@ describe('versioned site, pluginId=community', () => {
 
     expect(versionsMetadata).toEqual([
       // vCurrent removed
-      v100,
+      {...v100, versionBadge: false},
     ]);
   });
 
@@ -716,8 +719,10 @@ describe('versioned site, pluginId=community', () => {
         ...vCurrent,
         isLast: true,
         routePriority: -1,
+        tagsPath: '/communityBasePath/tags',
         versionPath: '/communityBasePath',
-        versionBanner: 'none',
+        versionBanner: null,
+        versionBadge: false,
       },
     ]);
   });

package/src/cli.ts

@@ -12,13 +12,10 @@ import {
 } from './versions';
 import fs from 'fs-extra';
 import path from 'path';
-import {
-  PathOptions,
-  UnprocessedSidebarItem,
-  UnprocessedSidebars,
-  SidebarOptions,
-} from './types';
-import {loadSidebars, resolveSidebarPathOption} from './sidebars';
+import type {PathOptions, SidebarOptions} from './types';
+import {transformSidebarItems} from './sidebars/utils';
+import type {SidebarItem, NormalizedSidebars, Sidebar} from './sidebars/types';
+import {loadUnprocessedSidebars, resolveSidebarPathOption} from './sidebars';
 import {DEFAULT_PLUGIN_ID} from '@docusaurus/core/lib/constants';
 
 function createVersionedSidebarFile({
@@ -35,7 +32,7 @@ function createVersionedSidebarFile({
   options: SidebarOptions;
 }) {
   // Load current sidebar and create a new versioned sidebars file (if needed).
-  const loadedSidebars = loadSidebars(sidebarPath, options);
+  const loadedSidebars = loadUnprocessedSidebars(sidebarPath, options);
 
   // Do not create a useless versioned sidebars file if sidebars file is empty or sidebars are disabled/false)
   const shouldCreateVersionedSidebarFile =
@@ -45,30 +42,27 @@ function createVersionedSidebarFile({
     // TODO @slorber: this "version prefix" in versioned sidebars looks like a bad idea to me
     // TODO try to get rid of it
     // Transform id in original sidebar to versioned id.
-    const normalizeItem = (
-      item: UnprocessedSidebarItem,
-    ): UnprocessedSidebarItem => {
-      switch (item.type) {
-        case 'category':
-          return {...item, items: item.items.map(normalizeItem)};
-        case 'ref':
-        case 'doc':
-          return {
-            type: item.type,
-            id: `version-${version}/${item.id}`,
-          };
-        default:
-          return item;
+    const prependVersion = (item: SidebarItem): SidebarItem => {
+      if (item.type === 'ref' || item.type === 'doc') {
+        return {
+          type: item.type,
+          id: `version-${version}/${item.id}`,
+        };
       }
+      return item;
     };
 
-    const versionedSidebar: UnprocessedSidebars = Object.entries(
-      loadedSidebars,
-    ).reduce((acc: UnprocessedSidebars, [sidebarId, sidebarItems]) => {
-      const newVersionedSidebarId = `version-${version}/${sidebarId}`;
-      acc[newVersionedSidebarId] = sidebarItems.map(normalizeItem);
-      return acc;
-    }, {});
+    const versionedSidebar = Object.entries(loadedSidebars).reduce(
+      (acc: NormalizedSidebars, [sidebarId, sidebar]) => {
+        const versionedId = `version-${version}/${sidebarId}`;
+        acc[versionedId] = transformSidebarItems(
+          sidebar as Sidebar,
+          prependVersion,
+        );
+        return acc;
+      },
+      {},
+    );
 
     const versionedSidebarsDir = getVersionedSidebarsDirPath(siteDir, pluginId);
     const newSidebarFile = path.join(
@@ -85,7 +79,6 @@ function createVersionedSidebarFile({
 }
 
 // Tests depend on non-default export for mocking.
-// eslint-disable-next-line import/prefer-default-export
 export function cliDocsVersionCommand(
   version: string | null | undefined,
   siteDir: string,

package/src/client/docsClientUtils.ts

@@ -20,22 +20,11 @@ export type ActivePlugin = {
   pluginData: GlobalPluginData;
 };
 
-export type GetActivePluginOptions = {failfast?: boolean};
+export type GetActivePluginOptions = {failfast?: boolean}; // use fail-fast option if you know for sure one plugin instance is active
 
 // get the data of the plugin that is currently "active"
 // ie the docs of that plugin are currently browsed
 // it is useful to support multiple docs plugin instances
-export function getActivePlugin(
-  allPluginDatas: Record<string, GlobalPluginData>,
-  pathname: string,
-  options: {failfast: true}, // use fail-fast option if you know for sure one plugin instance is active
-): ActivePlugin;
-export function getActivePlugin(
-  allPluginDatas: Record<string, GlobalPluginData>,
-  pathname: string,
-  options?: GetActivePluginOptions,
-): ActivePlugin | undefined;
-
 export function getActivePlugin(
   allPluginDatas: Record<string, GlobalPluginData>,
   pathname: string,

package/src/docFrontMatter.ts

@@ -5,11 +5,11 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-/* eslint-disable camelcase */
-
 import {
   JoiFrontMatter as Joi, // Custom instance for frontmatter
   URISchema,
+  FrontMatterTagsSchema,
+  FrontMatterTOCHeadingLevels,
   validateFrontMatter,
 } from '@docusaurus/utils-validation';
 import {DocFrontMatter} from './types';
@@ -29,9 +29,14 @@ const DocFrontMatterSchema = Joi.object<DocFrontMatter>({
   slug: Joi.string(),
   sidebar_label: Joi.string(),
   sidebar_position: Joi.number(),
+  sidebar_class_name: Joi.string(),
+  tags: FrontMatterTagsSchema,
   pagination_label: Joi.string(),
   custom_edit_url: URISchema.allow('', null),
   parse_number_prefixes: Joi.boolean(),
+  pagination_next: Joi.string().allow(null),
+  pagination_prev: Joi.string().allow(null),
+  ...FrontMatterTOCHeadingLevels,
 }).unknown();
 
 export function validateDocFrontMatter(

package/src/docs.ts

@@ -7,6 +7,8 @@
 
 import path from 'path';
 import fs from 'fs-extra';
+import chalk from 'chalk';
+import {keyBy} from 'lodash';
 import {
   aliasedSitePath,
   getEditUrl,
@@ -15,6 +17,7 @@ import {
   parseMarkdownString,
   posixPath,
   Globby,
+  normalizeFrontMatterTags,
 } from '@docusaurus/utils';
 import {LoadContext} from '@docusaurus/types';
 
@@ -22,17 +25,21 @@ import {getFileLastUpdate} from './lastUpdate';
 import {
   DocFile,
   DocMetadataBase,
+  DocMetadata,
+  DocNavLink,
   LastUpdateData,
   MetadataOptions,
   PluginOptions,
   VersionMetadata,
+  LoadedVersion,
 } from './types';
 import getSlug from './slug';
 import {CURRENT_VERSION_NAME} from './constants';
 import {getDocsDirPaths} from './versions';
 import {stripPathNumberPrefixes} from './numberPrefix';
 import {validateDocFrontMatter} from './docFrontMatter';
-import chalk from 'chalk';
+import type {Sidebars} from './sidebars/types';
+import {createSidebarsUtils} from './sidebars/utils';
 
 type LastUpdateOptions = Pick<
   PluginOptions,
@@ -130,9 +137,8 @@ function doProcessDocMetadata({
     custom_edit_url: customEditURL,
 
     // Strip number prefixes by default (01-MyFolder/01-MyDoc.md => MyFolder/MyDoc) by default,
-    // but allow to disable this behavior with frontmatterr
-    // eslint-disable-next-line camelcase
-    parse_number_prefixes = true,
+    // but allow to disable this behavior with frontmatter
+    parse_number_prefixes: parseNumberPrefixes = true,
   } = frontMatter;
 
   // ex: api/plugins/myDoc -> myDoc
@@ -146,8 +152,7 @@ function doProcessDocMetadata({
   // ex: myDoc -> .
   const sourceDirName = path.dirname(source);
 
-  // eslint-disable-next-line camelcase
-  const {filename: unprefixedFileName, numberPrefix} = parse_number_prefixes
+  const {filename: unprefixedFileName, numberPrefix} = parseNumberPrefixes
     ? options.numberPrefixParser(sourceFileNameWithoutExtension)
     : {filename: sourceFileNameWithoutExtension, numberPrefix: undefined};
 
@@ -175,8 +180,7 @@ function doProcessDocMetadata({
       return undefined;
     }
     // Eventually remove the number prefixes from intermediate directories
-    // eslint-disable-next-line camelcase
-    return parse_number_prefixes
+    return parseNumberPrefixes
       ? stripPathNumberPrefixes(sourceDirName, options.numberPrefixParser)
       : sourceDirName;
   }
@@ -203,7 +207,7 @@ function doProcessDocMetadata({
         baseID,
         dirName: sourceDirName,
         frontmatterSlug: frontMatter.slug,
-        stripDirNumberPrefixes: parse_number_prefixes,
+        stripDirNumberPrefixes: parseNumberPrefixes,
         numberPrefixParser: options.numberPrefixParser,
       });
 
@@ -255,6 +259,7 @@ function doProcessDocMetadata({
     slug: docSlug,
     permalink,
     editUrl: customEditURL !== undefined ? customEditURL : getDocEditUrl(),
+    tags: normalizeFrontMatterTags(versionMetadata.tagsPath, frontMatter.tags),
     version: versionMetadata.versionName,
     lastUpdatedBy: lastUpdate.lastUpdatedBy,
     lastUpdatedAt: lastUpdate.lastUpdatedAt,
@@ -285,3 +290,77 @@ export function processDocMetadata(args: {
     throw e;
   }
 }
+
+export function handleNavigation(
+  docsBase: DocMetadataBase[],
+  sidebars: Sidebars,
+  sidebarFilePath: string,
+): Pick<LoadedVersion, 'mainDocId' | 'docs'> {
+  const docsBaseById = keyBy(docsBase, (doc) => doc.id);
+  const {checkSidebarsDocIds, getDocNavigation, getFirstDocIdOfFirstSidebar} =
+    createSidebarsUtils(sidebars);
+
+  const validDocIds = Object.keys(docsBaseById);
+  checkSidebarsDocIds(validDocIds, sidebarFilePath);
+
+  // Add sidebar/next/previous to the docs
+  function addNavData(doc: DocMetadataBase): DocMetadata {
+    const {sidebarName, previousId, nextId} = getDocNavigation(doc.id);
+    const toDocNavLink = (
+      docId: string | null | undefined,
+      type: 'prev' | 'next',
+    ): DocNavLink | undefined => {
+      if (!docId) {
+        return undefined;
+      }
+      if (!docsBaseById[docId]) {
+        // This could only happen if user provided the ID through front matter
+        throw new Error(
+          `Error when loading ${doc.id} in ${doc.sourceDirName}: the pagination_${type} front matter points to a non-existent ID ${docId}.`,
+        );
+      }
+      const {
+        title,
+        permalink,
+        frontMatter: {
+          pagination_label: paginationLabel,
+          sidebar_label: sidebarLabel,
+        },
+      } = docsBaseById[docId];
+      return {title: paginationLabel ?? sidebarLabel ?? title, permalink};
+    };
+    const {
+      frontMatter: {
+        pagination_next: paginationNext = nextId,
+        pagination_prev: paginationPrev = previousId,
+      },
+    } = doc;
+    const previous = toDocNavLink(paginationPrev, 'prev');
+    const next = toDocNavLink(paginationNext, 'next');
+    return {...doc, sidebar: sidebarName, previous, next};
+  }
+  const docs = docsBase.map(addNavData);
+  // sort to ensure consistent output for tests
+  docs.sort((a, b) => a.id.localeCompare(b.id));
+
+  /**
+   * The "main doc" is the "version entry point"
+   * We browse this doc by clicking on a version:
+   * - the "home" doc (at '/docs/')
+   * - the first doc of the first sidebar
+   * - a random doc (if no docs are in any sidebar... edge case)
+   */
+  function getMainDoc(): DocMetadata {
+    const versionHomeDoc = docs.find((doc) => doc.slug === '/');
+    const firstDocIdOfFirstSidebar = getFirstDocIdOfFirstSidebar();
+    if (versionHomeDoc) {
+      return versionHomeDoc;
+    } else if (firstDocIdOfFirstSidebar) {
+      return docs.find((doc) => doc.id === firstDocIdOfFirstSidebar)!;
+    } else {
+      return docs[0];
+    }
+  }
+
+  return {mainDocId: getMainDoc().unversionedId, docs};
+}