@docusaurus/plugin-content-docs 2.0.0-beta.14 → 2.0.0-beta.15

package/lib/sidebars/types.d.ts

@@ -4,9 +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 { Optional } from 'utility-types';
-import type { DocMetadataBase, VersionMetadata, NumberPrefixParser, SidebarOptions } from '../types';
-import { Required } from 'utility-types';
+import type { Optional, Required } from 'utility-types';
+import type { DocMetadataBase, VersionMetadata } from '../types';
+import type { NumberPrefixParser, SidebarOptions, CategoryIndexMatcher } from '@docusaurus/plugin-content-docs';
 declare type Expand<T extends Record<string, unknown>> = {
     [P in keyof T]: T[P];
 };
@@ -43,6 +43,8 @@ export declare type SidebarItemCategoryLinkGeneratedIndexConfig = {
     slug?: string;
     title?: string;
     description?: string;
+    image?: string;
+    keywords?: string | readonly string[];
 };
 export declare type SidebarItemCategoryLinkGeneratedIndex = {
     type: 'generated-index';
@@ -50,6 +52,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;
@@ -117,6 +121,7 @@ export declare type SidebarItemsGeneratorArgs = {
     version: SidebarItemsGeneratorVersion;
     docs: SidebarItemsGeneratorDoc[];
     numberPrefixParser: NumberPrefixParser;
+    isCategoryIndex: CategoryIndexMatcher;
     options: SidebarOptions;
 };
 export declare type SidebarItemsGenerator = (generatorArgs: SidebarItemsGeneratorArgs) => Promise<SidebarItem[]>;

package/lib/sidebars/utils.d.ts

@@ -4,9 +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 { Sidebars, Sidebar, SidebarItem, SidebarItemCategory, SidebarItemLink, SidebarItemDoc, SidebarCategoriesShorthand, SidebarItemConfig } from './types';
-import { DocMetadataBase, DocNavLink } from '../types';
-import { SidebarItemCategoryWithGeneratedIndex, SidebarNavigationItem } from './types';
+import type { Sidebars, Sidebar, SidebarItem, SidebarItemCategory, SidebarItemLink, SidebarItemDoc, SidebarCategoriesShorthand, SidebarItemConfig, SidebarItemCategoryWithGeneratedIndex, SidebarNavigationItem } from './types';
+import type { DocMetadataBase, DocNavLink } from '../types';
 export declare function isCategoriesShorthand(item: SidebarItemConfig): item is SidebarCategoriesShorthand;
 export declare function transformSidebarItems(sidebar: Sidebar, updateFn: (item: SidebarItem) => SidebarItem): Sidebar;
 export declare function collectSidebarDocItems(sidebar: Sidebar): SidebarItemDoc[];
@@ -25,9 +24,18 @@ export declare type SidebarsUtils = {
     sidebars: Sidebars;
     getFirstDocIdOfFirstSidebar: () => string | undefined;
     getSidebarNameByDocId: (docId: string) => string | undefined;
-    getDocNavigation: (unversionedId: string, versionedId: string) => SidebarNavigation;
+    getDocNavigation: (unversionedId: string, versionedId: string, displayedSidebar: string | null | undefined) => 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

@@ -104,15 +104,20 @@ function createSidebarsUtils(sidebars) {
             next: undefined,
         };
     }
-    function getDocNavigation(unversionedId, versionedId) {
+    function getDocNavigation(unversionedId, versionedId, displayedSidebar) {
         // TODO legacy id retro-compatibility!
         let docId = unversionedId;
-        let sidebarName = getSidebarNameByDocId(docId);
-        if (!sidebarName) {
+        let sidebarName = displayedSidebar === undefined
+            ? getSidebarNameByDocId(docId)
+            : displayedSidebar;
+        if (sidebarName === undefined) {
             docId = versionedId;
             sidebarName = getSidebarNameByDocId(docId);
         }
         if (sidebarName) {
+            if (!sidebarNameToNavigationItems[sidebarName]) {
+                throw new Error(`Doc with ID ${docId} wants to display sidebar ${sidebarName} but a sidebar with this name doesn't exist`);
+            }
             const navigationItems = sidebarNameToNavigationItems[sidebarName];
             const currentItemIndex = navigationItems.findIndex((item) => {
                 if (item.type === 'doc') {
@@ -123,6 +128,9 @@ function createSidebarsUtils(sidebars) {
                 }
                 return false;
             });
+            if (currentItemIndex === -1) {
+                return { sidebarName, next: undefined, previous: undefined };
+            }
             const { previous, next } = (0, utils_1.getElementsAround)(navigationItems, currentItemIndex);
             return { sidebarName, previous, next };
         }
@@ -173,6 +181,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 +225,7 @@ Available document ids are:
         getCategoryGeneratedIndexList,
         getCategoryGeneratedIndexNavigation,
         checkSidebarsDocIds,
+        getFirstLink: (id) => getFirstLink(sidebars[id]),
     };
 }
 exports.createSidebarsUtils = createSidebarsUtils;

package/lib/sidebars/validation.d.ts

@@ -5,6 +5,6 @@
  * LICENSE file in the root directory of this source tree.
  */
 import type { SidebarsConfig } from './types';
-import { CategoryMetadataFile } from './generator';
+import type { CategoryMetadataFile } from './generator';
 export declare function validateSidebars(sidebars: unknown): asserts sidebars is SidebarsConfig;
 export declare function validateCategoryMetadataFile(unsafeContent: unknown): CategoryMetadataFile;

package/lib/sidebars/validation.js

@@ -9,6 +9,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.validateCategoryMetadataFile = exports.validateSidebars = void 0;
 const utils_validation_1 = require("@docusaurus/utils-validation");
 const utils_1 = require("./utils");
+// NOTE: we don't add any default values during validation on purpose!
+// Config types are exposed to users for typechecking and we use the same type in normalization
 const sidebarItemBaseSchema = utils_validation_1.Joi.object({
     className: utils_validation_1.Joi.string(),
     customProps: utils_validation_1.Joi.object().unknown(),
@@ -50,6 +52,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/slug.d.ts

@@ -4,11 +4,12 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import type { DocMetadataBase, NumberPrefixParser } from './types';
-export default function getSlug({ baseID, frontmatterSlug, source, sourceDirName, stripDirNumberPrefixes, numberPrefixParser, }: {
+import type { DocMetadataBase } from './types';
+import type { NumberPrefixParser } from '@docusaurus/plugin-content-docs';
+export default function getSlug({ baseID, frontMatterSlug, source, sourceDirName, stripDirNumberPrefixes, numberPrefixParser, }: {
     baseID: string;
-    frontmatterSlug?: string;
-    source: DocMetadataBase['slug'];
+    frontMatterSlug?: string;
+    source: DocMetadataBase['source'];
     sourceDirName: DocMetadataBase['sourceDirName'];
     stripDirNumberPrefixes?: boolean;
     numberPrefixParser?: NumberPrefixParser;

package/lib/slug.js

@@ -9,7 +9,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const utils_1 = require("@docusaurus/utils");
 const numberPrefix_1 = require("./numberPrefix");
 const docs_1 = require("./docs");
-function getSlug({ baseID, frontmatterSlug, source, sourceDirName, stripDirNumberPrefixes = true, numberPrefixParser = numberPrefix_1.DefaultNumberPrefixParser, }) {
+function getSlug({ baseID, frontMatterSlug, source, sourceDirName, stripDirNumberPrefixes = true, numberPrefixParser = numberPrefix_1.DefaultNumberPrefixParser, }) {
     function getDirNameSlug() {
         const dirNameStripped = stripDirNumberPrefixes
             ? (0, numberPrefix_1.stripPathNumberPrefixes)(sourceDirName, numberPrefixParser)
@@ -20,15 +20,16 @@ function getSlug({ baseID, frontmatterSlug, source, sourceDirName, stripDirNumbe
         return resolveDirname;
     }
     function computeSlug() {
-        if (frontmatterSlug === null || frontmatterSlug === void 0 ? void 0 : frontmatterSlug.startsWith('/')) {
-            return frontmatterSlug;
+        if (frontMatterSlug === null || frontMatterSlug === void 0 ? void 0 : frontMatterSlug.startsWith('/')) {
+            return frontMatterSlug;
         }
         else {
             const dirNameSlug = getDirNameSlug();
-            if (!frontmatterSlug && (0, docs_1.isConventionalDocIndex)({ source, sourceDirName })) {
+            if (!frontMatterSlug &&
+                (0, docs_1.isCategoryIndex)((0, docs_1.toCategoryIndexMatcherParam)({ source, sourceDirName }))) {
                 return dirNameSlug;
             }
-            const baseSlug = frontmatterSlug || baseID;
+            const baseSlug = frontMatterSlug || baseID;
             return (0, utils_1.resolvePathname)(baseSlug, getDirNameSlug());
         }
     }
@@ -36,8 +37,8 @@ function getSlug({ baseID, frontmatterSlug, source, sourceDirName, stripDirNumbe
         if (!(0, utils_1.isValidPathname)(slug)) {
             throw new Error(`We couldn't compute a valid slug for document with id "${baseID}" in "${sourceDirName}" directory.
 The slug we computed looks invalid: ${slug}.
-Maybe your slug frontmatter is incorrect or you use weird chars in the file path?
-By using the slug frontmatter, you should be able to fix this error, by using the slug of your choice:
+Maybe your slug front matter is incorrect or you use weird chars in the file path?
+By using the slug front matter, you should be able to fix this error, by using the slug of your choice:
 
 Example =>
 ---

package/lib/translations.js

@@ -33,7 +33,7 @@ function getNormalizedSidebarName({ versionName, sidebarName, }) {
 }
 /*
 // Do we need to translate doc metadata?
-// It seems translating frontmatter labels is good enough
+// It seems translating front matter labels is good enough
 function getDocTranslations(doc: DocMetadata): TranslationFileContent {
   return {
     [`${doc.unversionedId}.title`]: {

package/lib/types.d.ts

@@ -4,10 +4,10 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import type { RemarkAndRehypePluginOptions } from '@docusaurus/mdx-loader';
+import type { Sidebars } from './sidebars/types';
 import type { Tag, FrontMatterTag, Slugger } from '@docusaurus/utils';
 import type { BrokenMarkdownLink as IBrokenMarkdownLink, ContentPaths } from '@docusaurus/utils/lib/markdownLinks';
-import type { SidebarItemsGeneratorOption, Sidebars } from './sidebars/types';
+import type { VersionBanner, SidebarOptions } from '@docusaurus/plugin-content-docs';
 export declare type DocFile = {
     contentPath: string;
     filePath: string;
@@ -15,9 +15,8 @@ export declare type DocFile = {
     content: string;
     lastUpdate: LastUpdateData;
 };
-export declare type VersionName = string;
 export declare type VersionMetadata = ContentPaths & {
-    versionName: VersionName;
+    versionName: string;
     versionLabel: string;
     versionPath: string;
     tagsPath: string;
@@ -30,62 +29,10 @@ export declare type VersionMetadata = ContentPaths & {
     sidebarFilePath: string | false | undefined;
     routePriority: number | undefined;
 };
-export declare type EditUrlFunction = (editUrlParams: {
-    version: string;
-    versionDocsDirPath: string;
-    docPath: string;
-    permalink: string;
-    locale: string;
-}) => string | undefined;
-export declare type MetadataOptions = {
-    routeBasePath: string;
-    editUrl?: string | EditUrlFunction;
-    editCurrentVersion: boolean;
-    editLocalizedFiles: boolean;
-    showLastUpdateTime?: boolean;
-    showLastUpdateAuthor?: boolean;
-    numberPrefixParser: NumberPrefixParser;
-};
-export declare type PathOptions = {
-    path: string;
-    sidebarPath?: string | false | undefined;
-};
-export declare type VersionBanner = 'unreleased' | 'unmaintained';
-export declare type VersionOptions = {
-    path?: string;
-    label?: string;
-    banner?: 'none' | VersionBanner;
-    badge?: boolean;
-    className?: string;
-};
-export declare type VersionsOptions = {
-    lastVersion?: string;
-    versions: Record<string, VersionOptions>;
-    onlyIncludeVersions?: string[];
-};
-export declare type SidebarOptions = {
-    sidebarCollapsible: boolean;
-    sidebarCollapsed: boolean;
-};
 export declare type NormalizeSidebarsParams = SidebarOptions & {
     version: VersionMetadata;
     categoryLabelSlugger: Slugger;
 };
-export declare type PluginOptions = MetadataOptions & PathOptions & VersionsOptions & RemarkAndRehypePluginOptions & SidebarOptions & {
-    id: string;
-    include: string[];
-    exclude: string[];
-    docLayoutComponent: string;
-    docItemComponent: string;
-    docTagDocListComponent: string;
-    docTagsListComponent: string;
-    docCategoryGeneratedIndexComponent: string;
-    admonitions: Record<string, unknown>;
-    disableVersioning: boolean;
-    includeCurrentVersion: boolean;
-    sidebarItemsGenerator: SidebarItemsGeneratorOption;
-    tagsBasePath: string;
-};
 export declare type LastUpdateData = {
     lastUpdatedAt?: number;
     formattedLastUpdatedAt?: string;
@@ -104,6 +51,7 @@ export declare type DocFrontMatter = {
     sidebar_label?: string;
     sidebar_position?: number;
     sidebar_class_name?: string;
+    displayed_sidebar?: string | null;
     pagination_label?: string;
     custom_edit_url?: string | null;
     parse_number_prefixes?: boolean;
@@ -115,7 +63,7 @@ export declare type DocFrontMatter = {
 export declare type DocMetadataBase = LastUpdateData & {
     id: string;
     unversionedId: string;
-    version: VersionName;
+    version: string;
     title: string;
     description: string;
     source: string;
@@ -144,6 +92,8 @@ export declare type CategoryGeneratedIndexMetadata = {
     sidebar: string;
     previous?: DocNavLink;
     next?: DocNavLink;
+    image?: string;
+    keywords?: string | readonly string[];
 };
 export declare type SourceToPermalink = {
     [source: string]: string;
@@ -166,23 +116,6 @@ export declare type LoadedVersion = VersionMetadata & {
 export declare type LoadedContent = {
     loadedVersions: LoadedVersion[];
 };
-export declare type GlobalDoc = {
-    id: string;
-    path: string;
-    sidebar: string | undefined;
-};
-export declare type GlobalVersion = {
-    name: VersionName;
-    label: string;
-    isLast: boolean;
-    path: string;
-    mainDocId: string;
-    docs: GlobalDoc[];
-};
-export declare type GlobalPluginData = {
-    path: string;
-    versions: GlobalVersion[];
-};
 export declare type BrokenMarkdownLink = IBrokenMarkdownLink<VersionMetadata>;
 export declare type DocsMarkdownOption = {
     versionsMetadata: VersionMetadata[];
@@ -190,7 +123,3 @@ export declare type DocsMarkdownOption = {
     sourceToPermalink: SourceToPermalink;
     onBrokenMarkdownLink: (brokenMarkdownLink: BrokenMarkdownLink) => void;
 };
-export declare type NumberPrefixParser = (filename: string) => {
-    filename: string;
-    numberPrefix?: number;
-};

package/lib/versions.d.ts

@@ -4,7 +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 { PluginOptions, VersionMetadata } from './types';
+import type { VersionMetadata } from './types';
+import type { PluginOptions } from '@docusaurus/plugin-content-docs';
 import type { LoadContext } from '@docusaurus/types';
 export declare function getVersionedDocsDirPath(siteDir: string, pluginId: string): string;
 export declare function getVersionedSidebarsDirPath(siteDir: string, pluginId: string): string;
@@ -12,5 +13,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,8 +1,12 @@
 {
   "name": "@docusaurus/plugin-content-docs",
-  "version": "2.0.0-beta.14",
+  "version": "2.0.0-beta.15",
   "description": "Docs plugin for Docusaurus.",
   "main": "lib/index.js",
+  "exports": {
+    "./client": "./lib/client/index.js",
+    ".": "./lib/index.js"
+  },
   "types": "src/plugin-content-docs.d.ts",
   "scripts": {
     "build": "tsc",
@@ -18,18 +22,15 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/core": "2.0.0-beta.14",
-    "@docusaurus/logger": "2.0.0-beta.14",
-    "@docusaurus/mdx-loader": "2.0.0-beta.14",
-    "@docusaurus/utils": "2.0.0-beta.14",
-    "@docusaurus/utils-validation": "2.0.0-beta.14",
+    "@docusaurus/core": "2.0.0-beta.15",
+    "@docusaurus/logger": "2.0.0-beta.15",
+    "@docusaurus/mdx-loader": "2.0.0-beta.15",
+    "@docusaurus/utils": "2.0.0-beta.15",
+    "@docusaurus/utils-validation": "2.0.0-beta.15",
     "combine-promises": "^1.1.0",
-    "escape-string-regexp": "^4.0.0",
     "fs-extra": "^10.0.0",
-    "globby": "^11.0.2",
     "import-fresh": "^3.2.2",
     "js-yaml": "^4.0.0",
-    "loader-utils": "^2.0.0",
     "lodash": "^4.17.20",
     "remark-admonitions": "^1.2.1",
     "shelljs": "^0.8.4",
@@ -38,11 +39,12 @@
     "webpack": "^5.61.0"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "2.0.0-beta.14",
-    "@docusaurus/types": "2.0.0-beta.14",
+    "@docusaurus/module-type-aliases": "2.0.0-beta.15",
+    "@docusaurus/types": "2.0.0-beta.15",
     "@types/js-yaml": "^4.0.0",
     "@types/picomatch": "^2.2.1",
     "commander": "^5.1.0",
+    "escape-string-regexp": "^4.0.0",
     "picomatch": "^2.1.1",
     "utility-types": "^3.10.0"
   },
@@ -53,5 +55,5 @@
   "engines": {
     "node": ">=14"
   },
-  "gitHead": "c4824a8937d8f1aa0806667749cbc74058e2b294"
+  "gitHead": "6cfad16436c07d8d11e5c2e1486dc59afd483e33"
 }

package/src/categoryGeneratedIndex.ts

@@ -5,9 +5,9 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import {CategoryGeneratedIndexMetadata, DocMetadataBase} from './types';
-import {SidebarItemCategoryWithGeneratedIndex} from './sidebars/types';
-import {SidebarsUtils, toNavigationLink} from './sidebars/utils';
+import type {CategoryGeneratedIndexMetadata, DocMetadataBase} from './types';
+import type {SidebarItemCategoryWithGeneratedIndex} from './sidebars/types';
+import {type SidebarsUtils, toNavigationLink} from './sidebars/utils';
 import {createDocsByIdIndex} from './docs';
 
 function getCategoryGeneratedIndexMetadata({
@@ -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/cli.ts

@@ -12,7 +12,10 @@ import {
 } from './versions';
 import fs from 'fs-extra';
 import path from 'path';
-import type {PathOptions, SidebarOptions} from './types';
+import type {
+  PathOptions,
+  SidebarOptions,
+} from '@docusaurus/plugin-content-docs';
 import {loadSidebarsFile, resolveSidebarPathOption} from './sidebars';
 import {DEFAULT_PLUGIN_ID} from '@docusaurus/utils';
 import logger from '@docusaurus/logger';