@docusaurus/plugin-content-docs 0.0.0-4357 → 0.0.0-4365

package/lib/categoryGeneratedIndex.js

@@ -18,6 +18,8 @@ function getCategoryGeneratedIndexMetadata({ category, sidebarsUtils, docsById,
     return {
         title: (_a = category.link.title) !== null && _a !== void 0 ? _a : category.label,
         description: category.link.description,
+        image: category.link.image,
+        keywords: category.link.keywords,
         slug: category.link.slug,
         permalink: category.link.permalink,
         sidebar: sidebarName,

package/lib/globalData.d.ts

@@ -4,6 +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 { DocMetadata, GlobalDoc, LoadedVersion, GlobalVersion } from './types';
+import type { Sidebars } from './sidebars/types';
+import type { DocMetadata, GlobalDoc, LoadedVersion, GlobalVersion, GlobalSidebar } from './types';
 export declare function toGlobalDataDoc(doc: DocMetadata): GlobalDoc;
+export declare function toGlobalSidebars(sidebars: Sidebars, version: LoadedVersion): Record<string, GlobalSidebar>;
 export declare function toGlobalDataVersion(version: LoadedVersion): GlobalVersion;

package/lib/globalData.js

@@ -6,7 +6,10 @@
  * LICENSE file in the root directory of this source tree.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.toGlobalDataVersion = exports.toGlobalDataDoc = void 0;
+exports.toGlobalDataVersion = exports.toGlobalSidebars = exports.toGlobalDataDoc = void 0;
+const lodash_1 = require("lodash");
+const utils_1 = require("@docusaurus/utils");
+const utils_2 = require("./sidebars/utils");
 function toGlobalDataDoc(doc) {
     return {
         id: doc.unversionedId,
@@ -15,6 +18,24 @@ function toGlobalDataDoc(doc) {
     };
 }
 exports.toGlobalDataDoc = toGlobalDataDoc;
+function toGlobalSidebars(sidebars, version) {
+    const { getFirstLink } = (0, utils_2.createSidebarsUtils)(sidebars);
+    return (0, lodash_1.mapValues)(sidebars, (sidebar, sidebarId) => {
+        const firstLink = getFirstLink(sidebarId);
+        if (!firstLink) {
+            return {};
+        }
+        return {
+            link: {
+                path: firstLink.type === 'generated-index'
+                    ? (0, utils_1.normalizeUrl)([version.versionPath, firstLink.slug])
+                    : version.docs.find((doc) => doc.id === firstLink.id || doc.unversionedId === firstLink.id).permalink,
+                label: firstLink.label,
+            },
+        };
+    });
+}
+exports.toGlobalSidebars = toGlobalSidebars;
 function toGlobalDataVersion(version) {
     return {
         name: version.versionName,
@@ -23,6 +44,7 @@ function toGlobalDataVersion(version) {
         path: version.versionPath,
         mainDocId: version.mainDocId,
         docs: version.docs.map(toGlobalDataDoc),
+        sidebars: toGlobalSidebars(version.sidebars, version),
     };
 }
 exports.toGlobalDataVersion = toGlobalDataVersion;

package/lib/index.js

@@ -28,7 +28,7 @@ const categoryGeneratedIndex_1 = require("./categoryGeneratedIndex");
 async function pluginContentDocs(context, options) {
     var _a;
     const { siteDir, generatedFilesDir, baseUrl, siteConfig } = context;
-    const versionsMetadata = (0, versions_1.readVersionsMetadata)({ context, options });
+    const versionsMetadata = await (0, versions_1.readVersionsMetadata)({ context, options });
     const pluginId = (_a = options.id) !== null && _a !== void 0 ? _a : utils_1.DEFAULT_PLUGIN_ID;
     const pluginDataDirRoot = path_1.default.join(generatedFilesDir, 'docusaurus-plugin-content-docs');
     const dataDir = path_1.default.join(pluginDataDirRoot, pluginId);

package/lib/routes.js

@@ -14,13 +14,15 @@ const logger_1 = (0, tslib_1.__importDefault)(require("@docusaurus/logger"));
 async function createCategoryGeneratedIndexRoutes({ version, actions, docCategoryGeneratedIndexComponent, }) {
     const slugs = (0, utils_1.createSlugger)();
     async function createCategoryGeneratedIndexRoute(categoryGeneratedIndex) {
-        const { sidebar, title, description, slug, permalink, previous, next } = categoryGeneratedIndex;
+        const { sidebar, title, description, slug, permalink, previous, next, image, keywords, } = categoryGeneratedIndex;
         const propFileName = slugs.slug(`${version.versionPath}-${categoryGeneratedIndex.sidebar}-category-${categoryGeneratedIndex.title}`);
         const prop = {
             title,
             description,
             slug,
             permalink,
+            image,
+            keywords,
             navigation: {
                 previous,
                 next,

package/lib/sidebars/types.d.ts

@@ -42,6 +42,8 @@ export declare type SidebarItemCategoryLinkGeneratedIndexConfig = {
     slug?: string;
     title?: string;
     description?: string;
+    image?: string;
+    keywords?: string | readonly string[];
 };
 export declare type SidebarItemCategoryLinkGeneratedIndex = {
     type: 'generated-index';
@@ -49,6 +51,8 @@ export declare type SidebarItemCategoryLinkGeneratedIndex = {
     permalink: string;
     title?: string;
     description?: string;
+    image?: string;
+    keywords?: string | readonly string[];
 };
 export declare type SidebarItemCategoryLinkConfig = SidebarItemCategoryLinkDoc | SidebarItemCategoryLinkGeneratedIndexConfig;
 export declare type SidebarItemCategoryLink = SidebarItemCategoryLinkDoc | SidebarItemCategoryLinkGeneratedIndex;

package/lib/sidebars/utils.d.ts

@@ -27,6 +27,15 @@ export declare type SidebarsUtils = {
     getDocNavigation: (unversionedId: string, versionedId: string) => SidebarNavigation;
     getCategoryGeneratedIndexList: () => SidebarItemCategoryWithGeneratedIndex[];
     getCategoryGeneratedIndexNavigation: (categoryGeneratedIndexPermalink: string) => SidebarNavigation;
+    getFirstLink: (sidebarId: string) => {
+        type: 'doc';
+        id: string;
+        label: string;
+    } | {
+        type: 'generated-index';
+        slug: string;
+        label: string;
+    } | undefined;
     checkSidebarsDocIds: (validDocIds: string[], sidebarFilePath: string) => void;
 };
 export declare function createSidebarsUtils(sidebars: Sidebars): SidebarsUtils;

package/lib/sidebars/utils.js

@@ -173,6 +173,42 @@ Available document ids are:
 - ${(0, lodash_1.uniq)(validDocIds).sort().join('\n- ')}`);
         }
     }
+    function getFirstLink(sidebar) {
+        var _a, _b, _c;
+        // eslint-disable-next-line no-restricted-syntax
+        for (const item of sidebar) {
+            if (item.type === 'doc') {
+                return {
+                    type: 'doc',
+                    id: item.id,
+                    label: (_a = item.label) !== null && _a !== void 0 ? _a : item.id,
+                };
+            }
+            else if (item.type === 'category') {
+                if (((_b = item.link) === null || _b === void 0 ? void 0 : _b.type) === 'doc') {
+                    return {
+                        type: 'doc',
+                        id: item.link.id,
+                        label: item.label,
+                    };
+                }
+                else if (((_c = item.link) === null || _c === void 0 ? void 0 : _c.type) === 'generated-index') {
+                    return {
+                        type: 'generated-index',
+                        slug: item.link.slug,
+                        label: item.label,
+                    };
+                }
+                else {
+                    const firstSubItem = getFirstLink(item.items);
+                    if (firstSubItem) {
+                        return firstSubItem;
+                    }
+                }
+            }
+        }
+        return undefined;
+    }
     return {
         sidebars,
         getFirstDocIdOfFirstSidebar,
@@ -181,6 +217,7 @@ Available document ids are:
         getCategoryGeneratedIndexList,
         getCategoryGeneratedIndexNavigation,
         checkSidebarsDocIds,
+        getFirstLink: (id) => getFirstLink(sidebars[id]),
     };
 }
 exports.createSidebarsUtils = createSidebarsUtils;

package/lib/sidebars/validation.js

@@ -50,6 +50,8 @@ const sidebarItemCategoryLinkSchema = utils_validation_1.Joi.object()
                 // permalink: Joi.string().optional(), // No, this one is not in the user config, only in the normalized version
                 title: utils_validation_1.Joi.string().optional(),
                 description: utils_validation_1.Joi.string().optional(),
+                image: utils_validation_1.Joi.string().optional(),
+                keywords: [utils_validation_1.Joi.string(), utils_validation_1.Joi.array().items(utils_validation_1.Joi.string())],
             }),
         },
         {

package/lib/types.d.ts

@@ -144,6 +144,8 @@ export declare type CategoryGeneratedIndexMetadata = {
     sidebar: string;
     previous?: DocNavLink;
     next?: DocNavLink;
+    image?: string;
+    keywords?: string | readonly string[];
 };
 export declare type SourceToPermalink = {
     [source: string]: string;
@@ -178,6 +180,14 @@ export declare type GlobalVersion = {
     path: string;
     mainDocId: string;
     docs: GlobalDoc[];
+    sidebars?: Record<string, GlobalSidebar>;
+};
+export declare type GlobalSidebarLink = {
+    label: string;
+    path: string;
+};
+export declare type GlobalSidebar = {
+    link?: GlobalSidebarLink;
 };
 export declare type GlobalPluginData = {
     path: string;

package/lib/versions.d.ts

@@ -12,5 +12,5 @@ export declare function getVersionsFilePath(siteDir: string, pluginId: string):
 export declare function readVersionsMetadata({ context, options, }: {
     context: Pick<LoadContext, 'siteDir' | 'baseUrl' | 'i18n'>;
     options: Pick<PluginOptions, 'id' | 'path' | 'sidebarPath' | 'routeBasePath' | 'tagsBasePath' | 'includeCurrentVersion' | 'disableVersioning' | 'lastVersion' | 'versions' | 'onlyIncludeVersions' | 'editUrl' | 'editCurrentVersion'>;
-}): VersionMetadata[];
+}): Promise<VersionMetadata[]>;
 export declare function getDocsDirPaths(versionMetadata: Pick<VersionMetadata, 'contentPath' | 'contentPathLocalized'>): [string, string];

package/lib/versions.js

@@ -50,11 +50,10 @@ function ensureValidVersionArray(versionArray) {
     }
     versionArray.forEach(ensureValidVersionString);
 }
-// TODO not easy to make async due to many deps
-function readVersionsFile(siteDir, pluginId) {
+async function readVersionsFile(siteDir, pluginId) {
     const versionsFilePath = getVersionsFilePath(siteDir, pluginId);
-    if (fs_extra_1.default.existsSync(versionsFilePath)) {
-        const content = JSON.parse(fs_extra_1.default.readFileSync(versionsFilePath, 'utf8'));
+    if (await fs_extra_1.default.pathExists(versionsFilePath)) {
+        const content = JSON.parse(await fs_extra_1.default.readFile(versionsFilePath, 'utf8'));
         ensureValidVersionArray(content);
         return content;
     }
@@ -62,22 +61,21 @@ function readVersionsFile(siteDir, pluginId) {
         return null;
     }
 }
-// TODO not easy to make async due to many deps
-function readVersionNames(siteDir, options) {
-    const versionFileContent = readVersionsFile(siteDir, options.id);
+async function readVersionNames(siteDir, options) {
+    const versionFileContent = await readVersionsFile(siteDir, options.id);
     if (!versionFileContent && options.disableVersioning) {
-        throw new Error(`Docs: using "disableVersioning=${options.disableVersioning}" option on a non-versioned site does not make sense.`);
+        throw new Error(`Docs: using "disableVersioning: ${options.disableVersioning}" option on a non-versioned site does not make sense.`);
     }
     const versions = options.disableVersioning ? [] : versionFileContent !== null && versionFileContent !== void 0 ? versionFileContent : [];
-    // We add the current version at the beginning, unless
-    // - user don't want to
-    // - it's been explicitly added to versions.json
+    // We add the current version at the beginning, unless:
+    // - user don't want to; or
+    // - it's already been explicitly added to versions.json
     if (options.includeCurrentVersion &&
         !versions.includes(constants_1.CURRENT_VERSION_NAME)) {
         versions.unshift(constants_1.CURRENT_VERSION_NAME);
     }
     if (versions.length === 0) {
-        throw new Error(`It is not possible to use docs without any version. Please check the configuration of these options: "includeCurrentVersion=${options.includeCurrentVersion}", "disableVersioning=${options.disableVersioning}".`);
+        throw new Error(`It is not possible to use docs without any version. Please check the configuration of these options: "includeCurrentVersion: ${options.includeCurrentVersion}", "disableVersioning: ${options.disableVersioning}".`);
     }
     return versions;
 }
@@ -96,27 +94,23 @@ function getDocsDirPathLocalized({ siteDir, locale, pluginId, versionName, }) {
 }
 function getVersionMetadataPaths({ versionName, context, options, }) {
     const isCurrentVersion = versionName === constants_1.CURRENT_VERSION_NAME;
-    const contentPath = isCurrentVersion
-        ? path_1.default.resolve(context.siteDir, options.path)
-        : path_1.default.join(getVersionedDocsDirPath(context.siteDir, options.id), `version-${versionName}`);
     const contentPathLocalized = getDocsDirPathLocalized({
         siteDir: context.siteDir,
         locale: context.i18n.currentLocale,
         pluginId: options.id,
         versionName,
     });
-    function getSidebarFilePath() {
-        if (isCurrentVersion) {
-            return (0, sidebars_1.resolveSidebarPathOption)(context.siteDir, options.sidebarPath);
-        }
-        else {
-            return path_1.default.join(getVersionedSidebarsDirPath(context.siteDir, options.id), `version-${versionName}-sidebars.json`);
-        }
+    if (isCurrentVersion) {
+        return {
+            contentPath: path_1.default.resolve(context.siteDir, options.path),
+            contentPathLocalized,
+            sidebarFilePath: (0, sidebars_1.resolveSidebarPathOption)(context.siteDir, options.sidebarPath),
+        };
     }
     return {
-        contentPath,
+        contentPath: path_1.default.join(getVersionedDocsDirPath(context.siteDir, options.id), `version-${versionName}`),
         contentPathLocalized,
-        sidebarFilePath: getSidebarFilePath(),
+        sidebarFilePath: path_1.default.join(getVersionedSidebarsDirPath(context.siteDir, options.id), `version-${versionName}-sidebars.json`),
     };
 }
 function getVersionEditUrls({ contentPath, contentPathLocalized, context: { siteDir, i18n }, options: { id, path: currentVersionPath, editUrl, editCurrentVersion }, }) {
@@ -262,7 +256,7 @@ function checkVersionMetadataPaths({ versionMetadata, context, }) {
 Please set the docs "sidebarPath" field in your config file to:
 - a sidebars path that exists
 - false: to disable the sidebar
-- undefined: for Docusaurus generates it automatically`);
+- undefined: for Docusaurus to generate it automatically`);
     }
 }
 // TODO for retrocompatibility with existing behavior
@@ -280,7 +274,7 @@ function checkVersionsOptions(availableVersionNames, options) {
     const availableVersionNamesMsg = `Available version names are: ${availableVersionNames.join(', ')}`;
     if (options.lastVersion &&
         !availableVersionNames.includes(options.lastVersion)) {
-        throw new Error(`Docs option lastVersion=${options.lastVersion} is invalid. ${availableVersionNamesMsg}`);
+        throw new Error(`Docs option lastVersion: ${options.lastVersion} is invalid. ${availableVersionNamesMsg}`);
     }
     const unknownVersionConfigNames = (0, lodash_1.difference)(Object.keys(options.versions), availableVersionNames);
     if (unknownVersionConfigNames.length > 0) {
@@ -300,9 +294,11 @@ function checkVersionsOptions(availableVersionNames, options) {
         }
     }
 }
-// Filter versions according to provided options
-// Note: we preserve the order in which versions are provided
-// the order of the onlyIncludeVersions array does not matter
+/**
+ * Filter versions according to provided options.
+ * Note: we preserve the order in which versions are provided;
+ * the order of the onlyIncludeVersions array does not matter
+ */
 function filterVersions(versionNamesUnfiltered, options) {
     if (options.onlyIncludeVersions) {
         return versionNamesUnfiltered.filter((name) => (options.onlyIncludeVersions || []).includes(name));
@@ -311,10 +307,9 @@ function filterVersions(versionNamesUnfiltered, options) {
         return versionNamesUnfiltered;
     }
 }
-// TODO make this async (requires plugin init to be async)
-function readVersionsMetadata({ context, options, }) {
+async function readVersionsMetadata({ context, options, }) {
     var _a;
-    const versionNamesUnfiltered = readVersionNames(context.siteDir, options);
+    const versionNamesUnfiltered = await readVersionNames(context.siteDir, options);
     checkVersionsOptions(versionNamesUnfiltered, options);
     const versionNames = filterVersions(versionNamesUnfiltered, options);
     const lastVersionName = (_a = options.lastVersion) !== null && _a !== void 0 ? _a : getDefaultLastVersionName(versionNames);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/plugin-content-docs",
-  "version": "0.0.0-4357",
+  "version": "0.0.0-4365",
   "description": "Docs plugin for Docusaurus.",
   "main": "lib/index.js",
   "types": "src/plugin-content-docs.d.ts",
@@ -18,11 +18,11 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/core": "0.0.0-4357",
-    "@docusaurus/logger": "0.0.0-4357",
-    "@docusaurus/mdx-loader": "0.0.0-4357",
-    "@docusaurus/utils": "0.0.0-4357",
-    "@docusaurus/utils-validation": "0.0.0-4357",
+    "@docusaurus/core": "0.0.0-4365",
+    "@docusaurus/logger": "0.0.0-4365",
+    "@docusaurus/mdx-loader": "0.0.0-4365",
+    "@docusaurus/utils": "0.0.0-4365",
+    "@docusaurus/utils-validation": "0.0.0-4365",
     "combine-promises": "^1.1.0",
     "escape-string-regexp": "^4.0.0",
     "fs-extra": "^10.0.0",
@@ -38,8 +38,8 @@
     "webpack": "^5.61.0"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "0.0.0-4357",
-    "@docusaurus/types": "0.0.0-4357",
+    "@docusaurus/module-type-aliases": "0.0.0-4365",
+    "@docusaurus/types": "0.0.0-4365",
     "@types/js-yaml": "^4.0.0",
     "@types/picomatch": "^2.2.1",
     "commander": "^5.1.0",
@@ -53,5 +53,5 @@
   "engines": {
     "node": ">=14"
   },
-  "gitHead": "69a854a40c08a943c1ea556470a44574ebcc6979"
+  "gitHead": "c3975ea3f75f6f038c322fa23b6ffa2c46328007"
 }

package/src/categoryGeneratedIndex.ts

@@ -28,6 +28,8 @@ function getCategoryGeneratedIndexMetadata({
   return {
     title: category.link.title ?? category.label,
     description: category.link.description,
+    image: category.link.image,
+    keywords: category.link.keywords,
     slug: category.link.slug,
     permalink: category.link.permalink,
     sidebar: sidebarName,

package/src/globalData.ts

@@ -5,11 +5,16 @@
  * LICENSE file in the root directory of this source tree.
  */
 
+import {mapValues} from 'lodash';
+import {normalizeUrl} from '@docusaurus/utils';
+import type {Sidebars} from './sidebars/types';
+import {createSidebarsUtils} from './sidebars/utils';
 import type {
   DocMetadata,
   GlobalDoc,
   LoadedVersion,
   GlobalVersion,
+  GlobalSidebar,
 } from './types';
 
 export function toGlobalDataDoc(doc: DocMetadata): GlobalDoc {
@@ -20,6 +25,31 @@ export function toGlobalDataDoc(doc: DocMetadata): GlobalDoc {
   };
 }
 
+export function toGlobalSidebars(
+  sidebars: Sidebars,
+  version: LoadedVersion,
+): Record<string, GlobalSidebar> {
+  const {getFirstLink} = createSidebarsUtils(sidebars);
+  return mapValues(sidebars, (sidebar, sidebarId) => {
+    const firstLink = getFirstLink(sidebarId);
+    if (!firstLink) {
+      return {};
+    }
+    return {
+      link: {
+        path:
+          firstLink.type === 'generated-index'
+            ? normalizeUrl([version.versionPath, firstLink.slug])
+            : version.docs.find(
+                (doc) =>
+                  doc.id === firstLink.id || doc.unversionedId === firstLink.id,
+              )!.permalink,
+        label: firstLink.label,
+      },
+    };
+  });
+}
+
 export function toGlobalDataVersion(version: LoadedVersion): GlobalVersion {
   return {
     name: version.versionName,
@@ -28,5 +58,6 @@ export function toGlobalDataVersion(version: LoadedVersion): GlobalVersion {
     path: version.versionPath,
     mainDocId: version.mainDocId,
     docs: version.docs.map(toGlobalDataDoc),
+    sidebars: toGlobalSidebars(version.sidebars, version),
   };
 }

package/src/index.ts

@@ -64,7 +64,7 @@ export default async function pluginContentDocs(
 ): Promise<Plugin<LoadedContent>> {
   const {siteDir, generatedFilesDir, baseUrl, siteConfig} = context;
 
-  const versionsMetadata = readVersionsMetadata({context, options});
+  const versionsMetadata = await readVersionsMetadata({context, options});
 
   const pluginId = options.id ?? DEFAULT_PLUGIN_ID;
 

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

@@ -11,9 +11,10 @@ declare module '@docusaurus/plugin-content-docs' {
   export type VersionBanner = import('./types').VersionBanner;
   type GlobalDataVersion = import('./types').GlobalVersion;
   type GlobalDataDoc = import('./types').GlobalDoc;
+  type GlobalDataSidebar = import('./types').GlobalSidebar;
   type VersionTag = import('./types').VersionTag;
 
-  export type {GlobalDataVersion, GlobalDataDoc};
+  export type {GlobalDataVersion, GlobalDataDoc, GlobalDataSidebar};
 
   export type PropNavigationLink = {
     readonly title: string;
@@ -42,6 +43,8 @@ declare module '@docusaurus/plugin-content-docs' {
   export type PropCategoryGeneratedIndex = {
     title: string;
     description?: string;
+    image?: string;
+    keywords?: string | readonly string[];
     slug: string;
     permalink: string;
     navigation: PropNavigation;

package/src/routes.ts

@@ -30,8 +30,17 @@ export async function createCategoryGeneratedIndexRoutes({
   async function createCategoryGeneratedIndexRoute(
     categoryGeneratedIndex: CategoryGeneratedIndexMetadata,
   ): Promise<RouteConfig> {
-    const {sidebar, title, description, slug, permalink, previous, next} =
-      categoryGeneratedIndex;
+    const {
+      sidebar,
+      title,
+      description,
+      slug,
+      permalink,
+      previous,
+      next,
+      image,
+      keywords,
+    } = categoryGeneratedIndex;
 
     const propFileName = slugs.slug(
       `${version.versionPath}-${categoryGeneratedIndex.sidebar}-category-${categoryGeneratedIndex.title}`,
@@ -42,6 +51,8 @@ export async function createCategoryGeneratedIndexRoutes({
       description,
       slug,
       permalink,
+      image,
+      keywords,
       navigation: {
         previous,
         next,

package/src/sidebars/types.ts

@@ -52,6 +52,8 @@ export type SidebarItemCategoryLinkGeneratedIndexConfig = {
   slug?: string;
   title?: string;
   description?: string;
+  image?: string;
+  keywords?: string | readonly string[];
 };
 export type SidebarItemCategoryLinkGeneratedIndex = {
   type: 'generated-index';
@@ -59,6 +61,8 @@ export type SidebarItemCategoryLinkGeneratedIndex = {
   permalink: string;
   title?: string;
   description?: string;
+  image?: string;
+  keywords?: string | readonly string[];
 };
 
 export type SidebarItemCategoryLinkConfig =

package/src/sidebars/utils.ts

@@ -136,6 +136,18 @@ export type SidebarsUtils = {
   getCategoryGeneratedIndexNavigation: (
     categoryGeneratedIndexPermalink: string,
   ) => SidebarNavigation;
+  getFirstLink: (sidebarId: string) =>
+    | {
+        type: 'doc';
+        id: string;
+        label: string;
+      }
+    | {
+        type: 'generated-index';
+        slug: string;
+        label: string;
+      }
+    | undefined;
 
   checkSidebarsDocIds: (validDocIds: string[], sidebarFilePath: string) => void;
 };
@@ -264,6 +276,50 @@ Available document ids are:
     }
   }
 
+  function getFirstLink(sidebar: Sidebar):
+    | {
+        type: 'doc';
+        id: string;
+        label: string;
+      }
+    | {
+        type: 'generated-index';
+        slug: string;
+        label: string;
+      }
+    | undefined {
+    // eslint-disable-next-line no-restricted-syntax
+    for (const item of sidebar) {
+      if (item.type === 'doc') {
+        return {
+          type: 'doc',
+          id: item.id,
+          label: item.label ?? item.id,
+        };
+      } else if (item.type === 'category') {
+        if (item.link?.type === 'doc') {
+          return {
+            type: 'doc',
+            id: item.link.id,
+            label: item.label,
+          };
+        } else if (item.link?.type === 'generated-index') {
+          return {
+            type: 'generated-index',
+            slug: item.link.slug,
+            label: item.label,
+          };
+        } else {
+          const firstSubItem = getFirstLink(item.items);
+          if (firstSubItem) {
+            return firstSubItem;
+          }
+        }
+      }
+    }
+    return undefined;
+  }
+
   return {
     sidebars,
     getFirstDocIdOfFirstSidebar,
@@ -272,6 +328,7 @@ Available document ids are:
     getCategoryGeneratedIndexList,
     getCategoryGeneratedIndexNavigation,
     checkSidebarsDocIds,
+    getFirstLink: (id) => getFirstLink(sidebars[id]),
   };
 }
 

package/src/sidebars/validation.ts

@@ -70,6 +70,8 @@ const sidebarItemCategoryLinkSchema = Joi.object<SidebarItemCategoryLink>()
           // permalink: Joi.string().optional(), // No, this one is not in the user config, only in the normalized version
           title: Joi.string().optional(),
           description: Joi.string().optional(),
+          image: Joi.string().optional(),
+          keywords: [Joi.string(), Joi.array().items(Joi.string())],
         }),
       },
       {

package/src/types.ts

@@ -174,6 +174,8 @@ export type CategoryGeneratedIndexMetadata = {
   sidebar: string;
   previous?: DocNavLink;
   next?: DocNavLink;
+  image?: string;
+  keywords?: string | readonly string[];
 };
 
 export type SourceToPermalink = {
@@ -214,6 +216,17 @@ export type GlobalVersion = {
   path: string;
   mainDocId: string; // home doc (if docs homepage configured), or first doc
   docs: GlobalDoc[];
+  sidebars?: Record<string, GlobalSidebar>;
+};
+
+export type GlobalSidebarLink = {
+  label: string;
+  path: string;
+};
+
+export type GlobalSidebar = {
+  link?: GlobalSidebarLink;
+  // ... we may add other things here later
 };
 
 export type GlobalPluginData = {

package/src/versions.ts

@@ -87,11 +87,13 @@ function ensureValidVersionArray(
   versionArray.forEach(ensureValidVersionString);
 }
 
-// TODO not easy to make async due to many deps
-function readVersionsFile(siteDir: string, pluginId: string): string[] | null {
+async function readVersionsFile(
+  siteDir: string,
+  pluginId: string,
+): Promise<string[] | null> {
   const versionsFilePath = getVersionsFilePath(siteDir, pluginId);
-  if (fs.existsSync(versionsFilePath)) {
-    const content = JSON.parse(fs.readFileSync(versionsFilePath, 'utf8'));
+  if (await fs.pathExists(versionsFilePath)) {
+    const content = JSON.parse(await fs.readFile(versionsFilePath, 'utf8'));
     ensureValidVersionArray(content);
     return content;
   } else {
@@ -99,27 +101,26 @@ function readVersionsFile(siteDir: string, pluginId: string): string[] | null {
   }
 }
 
-// TODO not easy to make async due to many deps
-function readVersionNames(
+async function readVersionNames(
   siteDir: string,
   options: Pick<
     PluginOptions,
     'id' | 'disableVersioning' | 'includeCurrentVersion'
   >,
-): string[] {
-  const versionFileContent = readVersionsFile(siteDir, options.id);
+): Promise<string[]> {
+  const versionFileContent = await readVersionsFile(siteDir, options.id);
 
   if (!versionFileContent && options.disableVersioning) {
     throw new Error(
-      `Docs: using "disableVersioning=${options.disableVersioning}" option on a non-versioned site does not make sense.`,
+      `Docs: using "disableVersioning: ${options.disableVersioning}" option on a non-versioned site does not make sense.`,
     );
   }
 
   const versions = options.disableVersioning ? [] : versionFileContent ?? [];
 
-  // We add the current version at the beginning, unless
-  // - user don't want to
-  // - it's been explicitly added to versions.json
+  // We add the current version at the beginning, unless:
+  // - user don't want to; or
+  // - it's already been explicitly added to versions.json
   if (
     options.includeCurrentVersion &&
     !versions.includes(CURRENT_VERSION_NAME)
@@ -129,7 +130,7 @@ function readVersionNames(
 
   if (versions.length === 0) {
     throw new Error(
-      `It is not possible to use docs without any version. Please check the configuration of these options: "includeCurrentVersion=${options.includeCurrentVersion}", "disableVersioning=${options.disableVersioning}".`,
+      `It is not possible to use docs without any version. Please check the configuration of these options: "includeCurrentVersion: ${options.includeCurrentVersion}", "disableVersioning: ${options.disableVersioning}".`,
     );
   }
 
@@ -174,13 +175,6 @@ function getVersionMetadataPaths({
 > {
   const isCurrentVersion = versionName === CURRENT_VERSION_NAME;
 
-  const contentPath = isCurrentVersion
-    ? path.resolve(context.siteDir, options.path)
-    : path.join(
-        getVersionedDocsDirPath(context.siteDir, options.id),
-        `version-${versionName}`,
-      );
-
   const contentPathLocalized = getDocsDirPathLocalized({
     siteDir: context.siteDir,
     locale: context.i18n.currentLocale,
@@ -188,21 +182,27 @@ function getVersionMetadataPaths({
     versionName,
   });
 
-  function getSidebarFilePath() {
-    if (isCurrentVersion) {
-      return resolveSidebarPathOption(context.siteDir, options.sidebarPath);
-    } else {
-      return path.join(
-        getVersionedSidebarsDirPath(context.siteDir, options.id),
-        `version-${versionName}-sidebars.json`,
-      );
-    }
+  if (isCurrentVersion) {
+    return {
+      contentPath: path.resolve(context.siteDir, options.path),
+      contentPathLocalized,
+      sidebarFilePath: resolveSidebarPathOption(
+        context.siteDir,
+        options.sidebarPath,
+      ),
+    };
   }
 
   return {
-    contentPath,
+    contentPath: path.join(
+      getVersionedDocsDirPath(context.siteDir, options.id),
+      `version-${versionName}`,
+    ),
     contentPathLocalized,
-    sidebarFilePath: getSidebarFilePath(),
+    sidebarFilePath: path.join(
+      getVersionedSidebarsDirPath(context.siteDir, options.id),
+      `version-${versionName}-sidebars.json`,
+    ),
   };
 }
 
@@ -459,7 +459,7 @@ function checkVersionMetadataPaths({
 Please set the docs "sidebarPath" field in your config file to:
 - a sidebars path that exists
 - false: to disable the sidebar
-- undefined: for Docusaurus generates it automatically`);
+- undefined: for Docusaurus to generate it automatically`);
   }
 }
 
@@ -488,7 +488,7 @@ function checkVersionsOptions(
     !availableVersionNames.includes(options.lastVersion)
   ) {
     throw new Error(
-      `Docs option lastVersion=${options.lastVersion} is invalid. ${availableVersionNamesMsg}`,
+      `Docs option lastVersion: ${options.lastVersion} is invalid. ${availableVersionNamesMsg}`,
     );
   }
   const unknownVersionConfigNames = difference(
@@ -531,9 +531,11 @@ function checkVersionsOptions(
   }
 }
 
-// Filter versions according to provided options
-// Note: we preserve the order in which versions are provided
-// the order of the onlyIncludeVersions array does not matter
+/**
+ * Filter versions according to provided options.
+ * Note: we preserve the order in which versions are provided;
+ * the order of the onlyIncludeVersions array does not matter
+ */
 function filterVersions(
   versionNamesUnfiltered: string[],
   options: Pick<PluginOptions, 'onlyIncludeVersions'>,
@@ -547,8 +549,7 @@ function filterVersions(
   }
 }
 
-// TODO make this async (requires plugin init to be async)
-export function readVersionsMetadata({
+export async function readVersionsMetadata({
   context,
   options,
 }: {
@@ -568,8 +569,11 @@ export function readVersionsMetadata({
     | 'editUrl'
     | 'editCurrentVersion'
   >;
-}): VersionMetadata[] {
-  const versionNamesUnfiltered = readVersionNames(context.siteDir, options);
+}): Promise<VersionMetadata[]> {
+  const versionNamesUnfiltered = await readVersionNames(
+    context.siteDir,
+    options,
+  );
 
   checkVersionsOptions(versionNamesUnfiltered, options);