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

package/lib/categoryGeneratedIndex.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 { CategoryGeneratedIndexMetadata, DocMetadataBase } from './types';
-import { SidebarsUtils } from './sidebars/utils';
+import type { CategoryGeneratedIndexMetadata, DocMetadataBase } from './types';
+import { type SidebarsUtils } from './sidebars/utils';
 export declare function getCategoryGeneratedIndexMetadataList({ docs, sidebarsUtils, }: {
     sidebarsUtils: SidebarsUtils;
     docs: DocMetadataBase[];

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/cli.d.ts

@@ -4,5 +4,5 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import type { PathOptions, SidebarOptions } from './types';
+import type { PathOptions, SidebarOptions } from '@docusaurus/plugin-content-docs';
 export declare function cliDocsVersionCommand(version: string | null | undefined, siteDir: string, pluginId: string, options: PathOptions & SidebarOptions): void;

package/lib/client/docsClientUtils.d.ts

@@ -4,28 +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 { GlobalPluginData, GlobalVersion, GlobalDoc } from '../types';
-declare type Version = GlobalVersion;
-declare type Doc = GlobalDoc;
-export declare type ActivePlugin = {
-    pluginId: string;
-    pluginData: GlobalPluginData;
-};
-export declare type GetActivePluginOptions = {
-    failfast?: boolean;
-};
+import type { GlobalPluginData, GlobalVersion, GetActivePluginOptions, ActivePlugin, ActiveDocContext, DocVersionSuggestions } from '@docusaurus/plugin-content-docs/client';
 export declare function getActivePlugin(allPluginDatas: Record<string, GlobalPluginData>, pathname: string, options?: GetActivePluginOptions): ActivePlugin | undefined;
-export declare type ActiveDocContext = {
-    activeVersion?: Version;
-    activeDoc?: Doc;
-    alternateDocVersions: Record<string, Doc>;
-};
-export declare const getLatestVersion: (data: GlobalPluginData) => Version;
-export declare const getActiveVersion: (data: GlobalPluginData, pathname: string) => Version | undefined;
+export declare const getLatestVersion: (data: GlobalPluginData) => GlobalVersion;
+export declare const getActiveVersion: (data: GlobalPluginData, pathname: string) => GlobalVersion | undefined;
 export declare const getActiveDocContext: (data: GlobalPluginData, pathname: string) => ActiveDocContext;
-export declare type DocVersionSuggestions = {
-    latestVersionSuggestion: GlobalVersion;
-    latestDocSuggestion?: GlobalDoc;
-};
 export declare const getDocVersionSuggestions: (data: GlobalPluginData, pathname: string) => DocVersionSuggestions;
-export {};

package/lib/client/docsClientUtils.js

@@ -8,11 +8,15 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getDocVersionSuggestions = exports.getActiveDocContext = exports.getActiveVersion = exports.getLatestVersion = exports.getActivePlugin = void 0;
 const router_1 = require("@docusaurus/router");
+// This code is not part of the api surface, not in ./theme on purpose
 // 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
 function getActivePlugin(allPluginDatas, pathname, options = {}) {
-    const activeEntry = Object.entries(allPluginDatas).find(([_id, pluginData]) => !!(0, router_1.matchPath)(pathname, {
+    const activeEntry = Object.entries(allPluginDatas)
+        // A quick route sorting: '/android/foo' should match '/android' instead of '/'
+        .sort((a, b) => b[1].path.localeCompare(a[1].path))
+        .find(([, pluginData]) => !!(0, router_1.matchPath)(pathname, {
         path: pluginData.path,
         exact: false,
         strict: false,

package/lib/{theme/hooks/useDocs.d.ts → client/globalDataHooks.d.ts}

@@ -4,8 +4,7 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import { GlobalPluginData, GlobalVersion } from '../../types';
-import { ActivePlugin, ActiveDocContext, DocVersionSuggestions, GetActivePluginOptions } from '../../client/docsClientUtils';
+import type { GlobalPluginData, GlobalVersion, ActivePlugin, ActiveDocContext, DocVersionSuggestions, GetActivePluginOptions } from '@docusaurus/plugin-content-docs/client';
 export declare const useAllDocsData: () => Record<string, GlobalPluginData>;
 export declare const useDocsData: (pluginId: string | undefined) => GlobalPluginData;
 export declare const useActivePlugin: (options?: GetActivePluginOptions) => ActivePlugin | undefined;

package/lib/{theme/hooks/useDocs.js → client/globalDataHooks.js}

@@ -10,7 +10,7 @@ exports.useDocVersionSuggestions = exports.useActiveDocContext = exports.useActi
 const tslib_1 = require("tslib");
 const router_1 = require("@docusaurus/router");
 const useGlobalData_1 = (0, tslib_1.__importStar)(require("@docusaurus/useGlobalData"));
-const docsClientUtils_1 = require("../../client/docsClientUtils");
+const docsClientUtils_1 = require("./docsClientUtils");
 // Important to use a constant object to avoid React useEffect executions etc...,
 // see https://github.com/facebook/docusaurus/issues/5089
 const StableEmptyObject = {};
@@ -22,6 +22,7 @@ return (_a = (0, useGlobalData_1.default)()['docusaurus-plugin-content-docs']) !
 exports.useAllDocsData = useAllDocsData;
 const useDocsData = (pluginId) => (0, useGlobalData_1.usePluginData)('docusaurus-plugin-content-docs', pluginId);
 exports.useDocsData = useDocsData;
+// TODO this feature should be provided by docusaurus core
 const useActivePlugin = (options = {}) => {
     const data = (0, exports.useAllDocsData)();
     const { pathname } = (0, router_1.useLocation)();

package/lib/client/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+export * from './globalDataHooks';

package/lib/client/index.js

@@ -0,0 +1,10 @@
+"use strict";
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+(0, tslib_1.__exportStar)(require("./globalDataHooks"), exports);

package/lib/docFrontMatter.js

@@ -24,6 +24,7 @@ const DocFrontMatterSchema = utils_validation_1.JoiFrontMatter.object({
     sidebar_label: utils_validation_1.JoiFrontMatter.string(),
     sidebar_position: utils_validation_1.JoiFrontMatter.number(),
     sidebar_class_name: utils_validation_1.JoiFrontMatter.string(),
+    displayed_sidebar: utils_validation_1.JoiFrontMatter.string().allow(null),
     tags: utils_validation_1.FrontMatterTagsSchema,
     pagination_label: utils_validation_1.JoiFrontMatter.string(),
     custom_edit_url: utils_validation_1.URISchema.allow('', null),

package/lib/docs.d.ts

@@ -5,8 +5,9 @@
  * LICENSE file in the root directory of this source tree.
  */
 import type { LoadContext } from '@docusaurus/types';
-import { DocFile, DocMetadataBase, MetadataOptions, PluginOptions, VersionMetadata, LoadedVersion } from './types';
-import { SidebarsUtils } from './sidebars/utils';
+import type { DocFile, DocMetadataBase, VersionMetadata, LoadedVersion } from './types';
+import type { SidebarsUtils } from './sidebars/utils';
+import type { MetadataOptions, PluginOptions, CategoryIndexMatcher, CategoryIndexMatcherParam } from '@docusaurus/plugin-content-docs';
 declare type LastUpdateOptions = Pick<PluginOptions, 'showLastUpdateAuthor' | 'showLastUpdateTime'>;
 export declare function readDocFile(versionMetadata: Pick<VersionMetadata, 'contentPath' | 'contentPathLocalized'>, source: string, options: LastUpdateOptions): Promise<DocFile>;
 export declare function readVersionDocs(versionMetadata: VersionMetadata, options: Pick<PluginOptions, 'include' | 'exclude' | 'showLastUpdateAuthor' | 'showLastUpdateTime'>): Promise<DocFile[]>;
@@ -28,10 +29,22 @@ export declare function getMainDocId({ docs, sidebarsUtils, }: {
     docs: DocMetadataBase[];
     sidebarsUtils: SidebarsUtils;
 }): string;
-export declare function isConventionalDocIndex(doc: {
-    source: DocMetadataBase['slug'];
-    sourceDirName: DocMetadataBase['sourceDirName'];
-}): boolean;
+export declare const isCategoryIndex: CategoryIndexMatcher;
+export declare function toCategoryIndexMatcherParam({ source, sourceDirName, }: Pick<DocMetadataBase, 'source' | 'sourceDirName'>): CategoryIndexMatcherParam;
+/**
+ * guides/sidebar/autogenerated.md -> 'autogenerated', '.md', ['sidebar', 'guides']
+ */
+export declare function splitPath(str: string): {
+    /**
+     * The list of directories, from lowest level to highest.
+     * If there's no dir name, directories is ['.']
+     */
+    directories: string[];
+    /** The file name, without extension */
+    fileName: string;
+    /** The extension, with a leading dot */
+    extension: string;
+};
 export declare function getDocIds(doc: DocMetadataBase): [string, string];
 export declare function createDocsByIdIndex<Doc extends {
     id: string;

package/lib/docs.js

@@ -6,7 +6,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createDocsByIdIndex = exports.getDocIds = exports.isConventionalDocIndex = exports.getMainDocId = exports.addDocNavigation = exports.processDocMetadata = exports.readVersionDocs = exports.readDocFile = void 0;
+exports.createDocsByIdIndex = exports.getDocIds = exports.splitPath = exports.toCategoryIndexMatcherParam = exports.isCategoryIndex = exports.getMainDocId = exports.addDocNavigation = exports.processDocMetadata = exports.readVersionDocs = exports.readDocFile = void 0;
 const tslib_1 = require("tslib");
 const path_1 = (0, tslib_1.__importDefault)(require("path"));
 const fs_extra_1 = (0, tslib_1.__importDefault)(require("fs-extra"));
@@ -66,7 +66,7 @@ function doProcessDocMetadata({ docFile, versionMetadata, context, options, }) {
     const frontMatter = (0, docFrontMatter_1.validateDocFrontMatter)(unsafeFrontMatter);
     const { 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 frontmatter
+    // but allow to disable this behavior with front matter
     parse_number_prefixes: parseNumberPrefixes = true, } = frontMatter;
     // ex: api/plugins/myDoc -> myDoc
     // ex: myDoc -> myDoc
@@ -81,7 +81,7 @@ function doProcessDocMetadata({ docFile, versionMetadata, context, options, }) {
     if (baseID.includes('/')) {
         throw new Error(`Document id "${baseID}" cannot include slash.`);
     }
-    // For autogenerated sidebars, sidebar position can come from filename number prefix or frontmatter
+    // For autogenerated sidebars, sidebar position can come from filename number prefix or front matter
     const sidebarPosition = (_b = frontMatter.sidebar_position) !== null && _b !== void 0 ? _b : numberPrefix;
     // TODO legacy retrocompatibility
     // The same doc in 2 distinct version could keep the same id,
@@ -90,7 +90,7 @@ function doProcessDocMetadata({ docFile, versionMetadata, context, options, }) {
         ? undefined
         : `version-${versionMetadata.versionName}`;
     // TODO legacy retrocompatibility
-    // I think it's bad to affect the frontmatter id with the dirname?
+    // I think it's bad to affect the front matter id with the dirname?
     function computeDirNameIdPrefix() {
         if (sourceDirName === '.') {
             return undefined;
@@ -110,7 +110,7 @@ function doProcessDocMetadata({ docFile, versionMetadata, context, options, }) {
         baseID,
         source,
         sourceDirName,
-        frontmatterSlug: frontMatter.slug,
+        frontMatterSlug: frontMatter.slug,
         stripDirNumberPrefixes: parseNumberPrefixes,
         numberPrefixParser: options.numberPrefixParser,
     });
@@ -181,7 +181,7 @@ function addDocNavigation(docsBase, sidebarsUtils, sidebarFilePath) {
     sidebarsUtils.checkSidebarsDocIds(docsBase.flatMap(getDocIds), sidebarFilePath);
     // Add sidebar/next/previous to the docs
     function addNavData(doc) {
-        const navigation = sidebarsUtils.getDocNavigation(doc.unversionedId, doc.id);
+        const navigation = sidebarsUtils.getDocNavigation(doc.unversionedId, doc.id, doc.frontMatter.displayed_sidebar);
         const toNavigationLinkByDocId = (docId, type) => {
             if (!docId) {
                 return undefined;
@@ -232,26 +232,46 @@ function getMainDocId({ docs, sidebarsUtils, }) {
     return getMainDoc().unversionedId;
 }
 exports.getMainDocId = getMainDocId;
-function getLastPathSegment(str) {
-    return (0, lodash_1.last)(str.split('/'));
-}
 // By convention, Docusaurus considers some docs are "indexes":
 // - index.md
 // - readme.md
 // - <folder>/<folder>.md
 //
+// This function is the default implementation of this convention
+//
 // Those index docs produce a different behavior
 // - Slugs do not end with a weird "/index" suffix
 // - Auto-generated sidebar categories link to them as intro
-function isConventionalDocIndex(doc) {
-    // "@site/docs/folder/subFolder/subSubFolder/myDoc.md" => "myDoc"
-    const docName = path_1.default.parse(doc.source).name;
-    // "folder/subFolder/subSubFolder" => "subSubFolder"
-    const lastDirName = getLastPathSegment(doc.sourceDirName);
-    const eligibleDocIndexNames = ['index', 'readme', lastDirName.toLowerCase()];
-    return eligibleDocIndexNames.includes(docName.toLowerCase());
+const isCategoryIndex = ({ fileName, directories, }) => {
+    var _a;
+    const eligibleDocIndexNames = [
+        'index',
+        'readme',
+        (_a = directories[0]) === null || _a === void 0 ? void 0 : _a.toLowerCase(),
+    ];
+    return eligibleDocIndexNames.includes(fileName.toLowerCase());
+};
+exports.isCategoryIndex = isCategoryIndex;
+function toCategoryIndexMatcherParam({ source, sourceDirName, }) {
+    // source + sourceDirName are always posix-style
+    return {
+        fileName: path_1.default.posix.parse(source).name,
+        extension: path_1.default.posix.parse(source).ext,
+        directories: sourceDirName.split(path_1.default.posix.sep).reverse(),
+    };
+}
+exports.toCategoryIndexMatcherParam = toCategoryIndexMatcherParam;
+/**
+ * guides/sidebar/autogenerated.md -> 'autogenerated', '.md', ['sidebar', 'guides']
+ */
+function splitPath(str) {
+    return {
+        fileName: path_1.default.parse(str).name,
+        extension: path_1.default.parse(str).ext,
+        directories: path_1.default.dirname(str).split(path_1.default.sep).reverse(),
+    };
 }
-exports.isConventionalDocIndex = isConventionalDocIndex;
+exports.splitPath = splitPath;
 // Return both doc ids
 // TODO legacy retro-compatibility due to old versioned sidebars using versioned doc ids
 // ("id" should be removed & "versionedId" should be renamed to "id")

package/lib/globalData.d.ts

@@ -4,6 +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 { DocMetadata, GlobalDoc, LoadedVersion, GlobalVersion } from './types';
+import type { Sidebars } from './sidebars/types';
+import type { CategoryGeneratedIndexMetadata, DocMetadata, LoadedVersion } from './types';
+import type { GlobalVersion, GlobalSidebar, GlobalDoc } from '@docusaurus/plugin-content-docs/client';
 export declare function toGlobalDataDoc(doc: DocMetadata): GlobalDoc;
+export declare function toGlobalDataGeneratedIndex(doc: CategoryGeneratedIndexMetadata): 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.toGlobalDataGeneratedIndex = 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,32 @@ function toGlobalDataDoc(doc) {
     };
 }
 exports.toGlobalDataDoc = toGlobalDataDoc;
+function toGlobalDataGeneratedIndex(doc) {
+    return {
+        id: doc.slug,
+        path: doc.permalink,
+        sidebar: doc.sidebar,
+    };
+}
+exports.toGlobalDataGeneratedIndex = toGlobalDataGeneratedIndex;
+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,
@@ -22,7 +51,10 @@ function toGlobalDataVersion(version) {
         isLast: version.isLast,
         path: version.versionPath,
         mainDocId: version.mainDocId,
-        docs: version.docs.map(toGlobalDataDoc),
+        docs: version.docs
+            .map(toGlobalDataDoc)
+            .concat(version.categoryGeneratedIndices.map(toGlobalDataGeneratedIndex)),
+        sidebars: toGlobalSidebars(version.sidebars, version),
     };
 }
 exports.toGlobalDataVersion = toGlobalDataVersion;

package/lib/index.d.ts

@@ -5,6 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 import type { LoadContext, Plugin } from '@docusaurus/types';
-import { PluginOptions, LoadedContent } from './types';
-export default function pluginContentDocs(context: LoadContext, options: PluginOptions): Plugin<LoadedContent>;
+import type { LoadedContent } from './types';
+import type { PluginOptions } from '@docusaurus/plugin-content-docs';
+export default function pluginContentDocs(context: LoadContext, options: PluginOptions): Promise<Plugin<LoadedContent>>;
 export { validateOptions } from './options';

package/lib/index.js

@@ -25,22 +25,16 @@ const tags_1 = require("./tags");
 const routes_1 = require("./routes");
 const utils_2 = require("./sidebars/utils");
 const categoryGeneratedIndex_1 = require("./categoryGeneratedIndex");
-function pluginContentDocs(context, options) {
+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);
     const aliasedSource = (source) => `~docs/${(0, utils_1.posixPath)(path_1.default.relative(pluginDataDirRoot, source))}`;
     return {
         name: 'docusaurus-plugin-content-docs',
-        getThemePath() {
-            return path_1.default.resolve(__dirname, './theme');
-        },
-        getTypeScriptThemePath() {
-            return path_1.default.resolve(__dirname, '..', 'src', 'theme');
-        },
         extendCli(cli) {
             const isDefaultPluginId = pluginId === utils_1.DEFAULT_PLUGIN_ID;
             // Need to create one distinct command per plugin instance

package/lib/lastUpdate.js

@@ -35,11 +35,11 @@ async function getFileLastUpdate(filePath) {
             }
             return null;
         }
-        const result = shelljs_1.default.exec(`git log -1 --format=%ct,%an ${filePath}`, {
+        const result = shelljs_1.default.exec(`git log -1 --format=%ct,%an "${filePath}"`, {
             silent: true,
         });
         if (result.code !== 0) {
-            throw new Error(`Retrieval of git history failed at ${filePath} with exit code ${result.code}: ${result.stderr}`);
+            throw new Error(`Retrieval of git history failed at "${filePath}" with exit code ${result.code}: ${result.stderr}`);
         }
         return getTimestampAndAuthor(result.stdout.trim());
     }

package/lib/markdown/index.d.ts

@@ -4,6 +4,6 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import { DocsMarkdownOption } from '../types';
+import type { DocsMarkdownOption } from '../types';
 import type { LoaderContext } from 'webpack';
 export default function markdownLoader(this: LoaderContext<DocsMarkdownOption>, source: string): void;

package/lib/markdown/linkify.d.ts

@@ -4,5 +4,5 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import { DocsMarkdownOption } from '../types';
+import type { DocsMarkdownOption } from '../types';
 export declare function linkify(fileString: string, filePath: string, options: DocsMarkdownOption): string;

package/lib/numberPrefix.d.ts

@@ -4,7 +4,7 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import type { NumberPrefixParser } from './types';
+import type { NumberPrefixParser } from '@docusaurus/plugin-content-docs';
 export declare const DefaultNumberPrefixParser: NumberPrefixParser;
 export declare const DisabledNumberPrefixParser: NumberPrefixParser;
 export declare function stripNumberPrefix(str: string, parser: NumberPrefixParser): string;

package/lib/options.d.ts

@@ -4,7 +4,7 @@
  * 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 } from './types';
+import type { PluginOptions } from '@docusaurus/plugin-content-docs';
 import { Joi } from '@docusaurus/utils-validation';
 import type { OptionValidationContext, ValidationResult } from '@docusaurus/types';
 export declare const DEFAULT_OPTIONS: Omit<PluginOptions, 'id' | 'sidebarPath'>;

package/lib/routes.d.ts

@@ -4,12 +4,13 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import { PluginContentLoadedActions, RouteConfig } from '@docusaurus/types';
-import { DocMetadata, LoadedVersion } from './types';
-export declare function createCategoryGeneratedIndexRoutes({ version, actions, docCategoryGeneratedIndexComponent, }: {
+import type { PluginContentLoadedActions, RouteConfig } from '@docusaurus/types';
+import type { DocMetadata, LoadedVersion } from './types';
+export declare function createCategoryGeneratedIndexRoutes({ version, actions, docCategoryGeneratedIndexComponent, aliasedSource, }: {
     version: LoadedVersion;
     actions: PluginContentLoadedActions;
     docCategoryGeneratedIndexComponent: string;
+    aliasedSource: (str: string) => string;
 }): Promise<RouteConfig[]>;
 export declare function createDocRoutes({ docs, actions, docItemComponent, }: {
     docs: DocMetadata[];

package/lib/routes.js

@@ -11,16 +11,18 @@ const tslib_1 = require("tslib");
 const utils_1 = require("@docusaurus/utils");
 const props_1 = require("./props");
 const logger_1 = (0, tslib_1.__importDefault)(require("@docusaurus/logger"));
-async function createCategoryGeneratedIndexRoutes({ version, actions, docCategoryGeneratedIndexComponent, }) {
+async function createCategoryGeneratedIndexRoutes({ version, actions, docCategoryGeneratedIndexComponent, aliasedSource, }) {
     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,
@@ -32,7 +34,7 @@ async function createCategoryGeneratedIndexRoutes({ version, actions, docCategor
             component: docCategoryGeneratedIndexComponent,
             exact: true,
             modules: {
-                categoryGeneratedIndex: propData,
+                categoryGeneratedIndex: aliasedSource(propData),
             },
             // Same as doc, this sidebar route attribute permits to associate this subpage to the given sidebar
             ...(sidebar && { sidebar }),
@@ -75,6 +77,7 @@ async function createVersionRoutes({ loadedVersion, actions, docItemComponent, d
                     version,
                     actions,
                     docCategoryGeneratedIndexComponent,
+                    aliasedSource,
                 }),
             ]);
             const routes = [...docRoutes, ...sidebarsRoutes];

package/lib/sidebars/generator.js

@@ -41,18 +41,11 @@ async function readCategoryMetadataFile(categoryDirPath) {
             throw e;
         }
     }
-    // eslint-disable-next-line no-restricted-syntax
-    for (const ext of ['.json', '.yml', '.yaml']) {
-        // Simpler to use only posix paths for mocking file metadata in tests
-        const filePath = (0, utils_1.posixPath)(path_1.default.join(categoryDirPath, `${exports.CategoryMetadataFilenameBase}${ext}`));
-        if (await fs_extra_1.default.pathExists(filePath)) {
-            return tryReadFile(filePath);
-        }
-    }
-    return null;
+    const filePath = await (0, utils_1.findAsyncSequential)(['.json', '.yml', '.yaml'].map((ext) => (0, utils_1.posixPath)(path_1.default.join(categoryDirPath, `${exports.CategoryMetadataFilenameBase}${ext}`))), fs_extra_1.default.pathExists);
+    return filePath ? tryReadFile(filePath) : null;
 }
 // Comment for this feature: https://github.com/facebook/docusaurus/issues/3464#issuecomment-818670449
-const DefaultSidebarItemsGenerator = async ({ numberPrefixParser, docs: allDocs, options, item: { dirName: autogenDir }, version, }) => {
+const DefaultSidebarItemsGenerator = async ({ numberPrefixParser, isCategoryIndex, docs: allDocs, options, item: { dirName: autogenDir }, version, }) => {
     const docsById = (0, docs_1.createDocsByIdIndex)(allDocs);
     const findDoc = (docId) => docsById[docId];
     const getDoc = (docId) => {
@@ -101,13 +94,12 @@ const DefaultSidebarItemsGenerator = async ({ numberPrefixParser, docs: allDocs,
         docs.forEach((doc) => {
             const breadcrumb = getRelativeBreadcrumb(doc);
             let currentDir = treeRoot; // We walk down the file's path to generate the fs structure
-            // eslint-disable-next-line no-restricted-syntax
-            for (const dir of breadcrumb) {
+            breadcrumb.forEach((dir) => {
                 if (typeof currentDir[dir] === 'undefined') {
                     currentDir[dir] = {}; // Create new folder.
                 }
                 currentDir = currentDir[dir]; // Go into the subdirectory.
-            }
+            });
             currentDir[`${docIdPrefix}${doc.id}`] = null; // We've walked through the file path. Register the file in this directory.
         });
         return treeRoot;
@@ -141,7 +133,13 @@ const DefaultSidebarItemsGenerator = async ({ numberPrefixParser, docs: allDocs,
                 return allItems.find((item) => item.type === 'doc' && getLocalDocId(item.id) === localId);
             }
             function findConventionalCategoryDocLink() {
-                return allItems.find((item) => item.type === 'doc' && (0, docs_1.isConventionalDocIndex)(getDoc(item.id)));
+                return allItems.find((item) => {
+                    if (item.type !== 'doc') {
+                        return false;
+                    }
+                    const doc = getDoc(item.id);
+                    return isCategoryIndex((0, docs_1.toCategoryIndexMatcherParam)(doc));
+                });
             }
             function getCategoryLinkedDocId() {
                 var _a, _b;

package/lib/sidebars/index.d.ts

@@ -5,8 +5,9 @@
  * LICENSE file in the root directory of this source tree.
  */
 import type { SidebarsConfig, Sidebars, NormalizedSidebars } from './types';
-import type { NormalizeSidebarsParams, PluginOptions } from '../types';
-import { SidebarProcessorParams } from './processor';
+import type { NormalizeSidebarsParams } from '../types';
+import { type SidebarProcessorParams } from './processor';
+import type { PluginOptions } from '@docusaurus/plugin-content-docs';
 export declare const DefaultSidebars: SidebarsConfig;
 export declare const DisabledSidebars: SidebarsConfig;
 export declare function resolveSidebarPathOption(siteDir: string, sidebarPathOption: PluginOptions['sidebarPath']): PluginOptions['sidebarPath'];

package/lib/sidebars/processor.d.ts

@@ -4,9 +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 { NumberPrefixParser, DocMetadataBase, VersionMetadata, SidebarOptions } from '../types';
+import type { DocMetadataBase, VersionMetadata } from '../types';
 import type { Sidebars, NormalizedSidebars, SidebarItemsGeneratorOption } from './types';
-import { Slugger } from '@docusaurus/utils';
+import type { Slugger } from '@docusaurus/utils';
+import type { NumberPrefixParser, SidebarOptions } from '@docusaurus/plugin-content-docs';
 export declare type SidebarProcessorParams = {
     sidebarItemsGenerator: SidebarItemsGeneratorOption;
     numberPrefixParser: NumberPrefixParser;

package/lib/sidebars/processor.js

@@ -13,6 +13,7 @@ const generator_1 = require("./generator");
 const lodash_1 = require("lodash");
 const combine_promises_1 = (0, tslib_1.__importDefault)(require("combine-promises"));
 const normalization_1 = require("./normalization");
+const docs_1 = require("../docs");
 function toSidebarItemsGeneratorDoc(doc) {
     return (0, lodash_1.pick)(doc, [
         'id',
@@ -46,6 +47,7 @@ async function processSidebar(unprocessedSidebar, params) {
             item,
             numberPrefixParser,
             defaultSidebarItemsGenerator: generator_1.DefaultSidebarItemsGenerator,
+            isCategoryIndex: docs_1.isCategoryIndex,
             ...getSidebarItemsGeneratorDocsAndVersion(),
             options: sidebarOptions,
         });