@docusaurus/plugin-content-docs 2.0.0-beta.17 → 2.0.0-beta.18

package/lib/categoryGeneratedIndex.js

@@ -11,9 +11,6 @@ const utils_1 = require("./sidebars/utils");
 const docs_1 = require("./docs");
 function getCategoryGeneratedIndexMetadata({ category, sidebarsUtils, docsById, }) {
     const { sidebarName, previous, next } = sidebarsUtils.getCategoryGeneratedIndexNavigation(category.link.permalink);
-    if (!sidebarName) {
-        throw new Error('unexpected');
-    }
     return {
         title: category.link.title ?? category.label,
         description: category.link.description,

package/lib/cli.js

@@ -26,8 +26,7 @@ async function createVersionedSidebarFile({ siteDir, pluginId, sidebarPath, vers
     if (shouldCreateVersionedSidebarFile) {
         const versionedSidebarsDir = (0, versions_1.getVersionedSidebarsDirPath)(siteDir, pluginId);
         const newSidebarFile = path_1.default.join(versionedSidebarsDir, `version-${version}-sidebars.json`);
-        await fs_extra_1.default.ensureDir(path_1.default.dirname(newSidebarFile));
-        await fs_extra_1.default.writeFile(newSidebarFile, `${JSON.stringify(sidebars, null, 2)}\n`, 'utf8');
+        await fs_extra_1.default.outputFile(newSidebarFile, `${JSON.stringify(sidebars, null, 2)}\n`, 'utf8');
     }
 }
 // Tests depend on non-default export for mocking.
@@ -47,7 +46,7 @@ async function cliDocsVersionCommand(version, siteDir, pluginId, options) {
     // Since we are going to create `version-${version}` folder, we need to make
     // sure it's a valid pathname.
     // eslint-disable-next-line no-control-regex
-    if (/[<>:"|?*\x00-\x1F]/g.test(version)) {
+    if (/[<>:"|?*\x00-\x1F]/.test(version)) {
         throw new Error(`${pluginIdLogPrefix}: invalid version tag specified! Please ensure its a valid pathname too. Try something like: 1.0.0.`);
     }
     if (/^\.\.?$/.test(version)) {
@@ -83,8 +82,7 @@ async function cliDocsVersionCommand(version, siteDir, pluginId, options) {
     });
     // Update versions.json file.
     versions.unshift(version);
-    await fs_extra_1.default.ensureDir(path_1.default.dirname(versionsJSONFile));
-    await fs_extra_1.default.writeFile(versionsJSONFile, `${JSON.stringify(versions, null, 2)}\n`);
+    await fs_extra_1.default.outputFile(versionsJSONFile, `${JSON.stringify(versions, null, 2)}\n`);
     logger_1.default.success `name=${pluginIdLogPrefix}: version name=${version} created!`;
 }
 exports.cliDocsVersionCommand = cliDocsVersionCommand;

package/lib/client/docsClientUtils.d.ts

@@ -5,7 +5,9 @@
  * LICENSE file in the root directory of this source tree.
  */
 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 function getActivePlugin(allPluginData: {
+    [pluginId: string]: GlobalPluginData;
+}, pathname: string, options?: GetActivePluginOptions): ActivePlugin | 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;

package/lib/client/docsClientUtils.js

@@ -12,8 +12,8 @@ const router_1 = require("@docusaurus/router");
 // 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)
+function getActivePlugin(allPluginData, pathname, options = {}) {
+    const activeEntry = Object.entries(allPluginData)
         // 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, {
@@ -25,7 +25,7 @@ function getActivePlugin(allPluginDatas, pathname, options = {}) {
         ? { pluginId: activeEntry[0], pluginData: activeEntry[1] }
         : undefined;
     if (!activePlugin && options.failfast) {
-        throw new Error(`Can't find active docs plugin for "${pathname}" pathname, while it was expected to be found. Maybe you tried to use a docs feature that can only be used on a docs-related page? Existing docs plugin paths are: ${Object.values(allPluginDatas)
+        throw new Error(`Can't find active docs plugin for "${pathname}" pathname, while it was expected to be found. Maybe you tried to use a docs feature that can only be used on a docs-related page? Existing docs plugin paths are: ${Object.values(allPluginData)
             .map((plugin) => plugin.path)
             .join(', ')}`);
     }

package/lib/client/index.d.ts

@@ -5,7 +5,9 @@
  * LICENSE file in the root directory of this source tree.
  */
 import type { GlobalPluginData, GlobalVersion, ActivePlugin, ActiveDocContext, DocVersionSuggestions, GetActivePluginOptions } from '@docusaurus/plugin-content-docs/client';
-export declare const useAllDocsData: () => Record<string, GlobalPluginData>;
+export declare const useAllDocsData: () => {
+    [pluginId: string]: GlobalPluginData;
+};
 export declare const useDocsData: (pluginId: string | undefined) => GlobalPluginData;
 export declare const useActivePlugin: (options?: GetActivePluginOptions) => ActivePlugin | undefined;
 export declare const useActivePluginAndVersion: (options?: GetActivePluginOptions) => {

package/lib/docs.d.ts

@@ -30,25 +30,16 @@ export declare function getMainDocId({ docs, sidebarsUtils, }: {
     sidebarsUtils: SidebarsUtils;
 }): string;
 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 toCategoryIndexMatcherParam({ source, sourceDirName, }: Pick<DocMetadataBase, 'source' | 'sourceDirName'>): CategoryIndexMatcherParam;
 export declare function getDocIds(doc: DocMetadataBase): [string, string];
 export declare function createDocsByIdIndex<Doc extends {
     id: string;
     unversionedId: string;
-}>(docs: Doc[]): Record<string, Doc>;
+}>(docs: Doc[]): {
+    [docId: string]: Doc;
+};
 export {};

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.splitPath = exports.toCategoryIndexMatcherParam = exports.isCategoryIndex = exports.getMainDocId = exports.addDocNavigation = exports.processDocMetadata = exports.readVersionDocs = exports.readDocFile = void 0;
+exports.createDocsByIdIndex = exports.getDocIds = exports.toCategoryIndexMatcherParam = exports.isCategoryIndex = exports.getMainDocId = exports.addDocNavigation = exports.processDocMetadata = exports.readVersionDocs = exports.readDocFile = void 0;
 const tslib_1 = require("tslib");
 const path_1 = tslib_1.__importDefault(require("path"));
 const fs_extra_1 = tslib_1.__importDefault(require("fs-extra"));
@@ -17,7 +17,7 @@ const slug_1 = tslib_1.__importDefault(require("./slug"));
 const constants_1 = require("./constants");
 const versions_1 = require("./versions");
 const numberPrefix_1 = require("./numberPrefix");
-const docFrontMatter_1 = require("./docFrontMatter");
+const frontMatter_1 = require("./frontMatter");
 const utils_2 = require("./sidebars/utils");
 async function readLastUpdateData(filePath, options) {
     const { showLastUpdateAuthor, showLastUpdateTime } = options;
@@ -61,7 +61,7 @@ function doProcessDocMetadata({ docFile, versionMetadata, context, options, }) {
     const { source, content, lastUpdate, contentPath, filePath } = docFile;
     const { siteDir, i18n } = context;
     const { frontMatter: unsafeFrontMatter, contentTitle, excerpt, } = (0, utils_1.parseMarkdownString)(content);
-    const frontMatter = (0, docFrontMatter_1.validateDocFrontMatter)(unsafeFrontMatter);
+    const frontMatter = (0, frontMatter_1.validateDocFrontMatter)(unsafeFrontMatter);
     const { custom_edit_url: customEditURL, 
     // Strip number prefixes by default
     // (01-MyFolder/01-MyDoc.md => MyFolder/MyDoc)
@@ -248,6 +248,10 @@ const isCategoryIndex = ({ fileName, directories, }) => {
     return eligibleDocIndexNames.includes(fileName.toLowerCase());
 };
 exports.isCategoryIndex = isCategoryIndex;
+/**
+ * `guides/sidebar/autogenerated.md` ->
+ *   `'autogenerated', '.md', ['sidebar', 'guides']`
+ */
 function toCategoryIndexMatcherParam({ source, sourceDirName, }) {
     // source + sourceDirName are always posix-style
     return {
@@ -257,18 +261,6 @@ function toCategoryIndexMatcherParam({ source, sourceDirName, }) {
     };
 }
 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.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

package/lib/{docFrontMatter.d.ts → frontMatter.d.ts}

@@ -5,4 +5,6 @@
  * LICENSE file in the root directory of this source tree.
  */
 import type { DocFrontMatter } from './types';
-export declare function validateDocFrontMatter(frontMatter: Record<string, unknown>): DocFrontMatter;
+export declare function validateDocFrontMatter(frontMatter: {
+    [key: string]: unknown;
+}): DocFrontMatter;

package/lib/globalData.d.ts

@@ -4,10 +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 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>;
+import type { LoadedVersion } from './types';
+import type { GlobalVersion } from '@docusaurus/plugin-content-docs/client';
 export declare function toGlobalDataVersion(version: LoadedVersion): GlobalVersion;

package/lib/globalData.js

@@ -6,11 +6,10 @@
  * LICENSE file in the root directory of this source tree.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.toGlobalDataVersion = exports.toGlobalSidebars = exports.toGlobalDataGeneratedIndex = exports.toGlobalDataDoc = void 0;
+exports.toGlobalDataVersion = void 0;
 const tslib_1 = require("tslib");
 const lodash_1 = tslib_1.__importDefault(require("lodash"));
-const utils_1 = require("@docusaurus/utils");
-const utils_2 = require("./sidebars/utils");
+const utils_1 = require("./sidebars/utils");
 function toGlobalDataDoc(doc) {
     return {
         id: doc.unversionedId,
@@ -18,7 +17,6 @@ function toGlobalDataDoc(doc) {
         sidebar: doc.sidebar,
     };
 }
-exports.toGlobalDataDoc = toGlobalDataDoc;
 function toGlobalDataGeneratedIndex(doc) {
     return {
         id: doc.slug,
@@ -26,9 +24,8 @@ function toGlobalDataGeneratedIndex(doc) {
         sidebar: doc.sidebar,
     };
 }
-exports.toGlobalDataGeneratedIndex = toGlobalDataGeneratedIndex;
 function toGlobalSidebars(sidebars, version) {
-    const { getFirstLink } = (0, utils_2.createSidebarsUtils)(sidebars);
+    const { getFirstLink } = (0, utils_1.createSidebarsUtils)(sidebars);
     return lodash_1.default.mapValues(sidebars, (sidebar, sidebarId) => {
         const firstLink = getFirstLink(sidebarId);
         if (!firstLink) {
@@ -37,14 +34,13 @@ function toGlobalSidebars(sidebars, version) {
         return {
             link: {
                 path: firstLink.type === 'generated-index'
-                    ? (0, utils_1.normalizeUrl)([version.versionPath, firstLink.slug])
+                    ? firstLink.permalink
                     : 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,

package/lib/lastUpdate.d.ts

@@ -4,9 +4,7 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-declare type FileLastUpdateData = {
-    timestamp?: number;
-    author?: string;
-};
-export declare function getFileLastUpdate(filePath?: string): Promise<FileLastUpdateData | null>;
-export {};
+export declare function getFileLastUpdate(filePath?: string): Promise<{
+    timestamp: number;
+    author: string;
+} | null>;

package/lib/lastUpdate.js

@@ -11,6 +11,7 @@ const tslib_1 = require("tslib");
 const logger_1 = tslib_1.__importDefault(require("@docusaurus/logger"));
 const utils_1 = require("@docusaurus/utils");
 let showedGitRequirementError = false;
+let showedFileNotTrackedError = false;
 async function getFileLastUpdate(filePath) {
     if (!filePath) {
         return null;
@@ -25,12 +26,20 @@ async function getFileLastUpdate(filePath) {
         return { timestamp: result.timestamp, author: result.author };
     }
     catch (err) {
-        if (err instanceof utils_1.GitNotFoundError && !showedGitRequirementError) {
-            logger_1.default.warn('Sorry, the docs plugin last update options require Git.');
-            showedGitRequirementError = true;
+        if (err instanceof utils_1.GitNotFoundError) {
+            if (!showedGitRequirementError) {
+                logger_1.default.warn('Sorry, the docs plugin last update options require Git.');
+                showedGitRequirementError = true;
+            }
+        }
+        else if (err instanceof utils_1.FileNotTrackedError) {
+            if (!showedFileNotTrackedError) {
+                logger_1.default.warn('Cannot infer the update date for some files, as they are not tracked by git.');
+                showedFileNotTrackedError = true;
+            }
         }
         else {
-            logger_1.default.error(err);
+            logger_1.default.warn(err);
         }
         return null;
     }

package/lib/markdown/index.js

@@ -11,6 +11,6 @@ function markdownLoader(source) {
     const fileString = source;
     const callback = this.async();
     const options = this.getOptions();
-    return (callback && callback(null, (0, linkify_1.linkify)(fileString, this.resourcePath, options)));
+    return callback?.(null, (0, linkify_1.linkify)(fileString, this.resourcePath, options));
 }
 exports.default = markdownLoader;

package/lib/markdown/linkify.js

@@ -11,6 +11,10 @@ const versions_1 = require("../versions");
 const utils_1 = require("@docusaurus/utils");
 function getVersion(filePath, options) {
     const versionFound = options.versionsMetadata.find((version) => (0, versions_1.getDocsDirPaths)(version).some((docsDirPath) => filePath.startsWith(docsDirPath)));
+    // At this point, this should never happen, because the MDX loaders' paths are
+    // literally using the version content paths; but if we allow sourcing content
+    // from outside the docs directory (through the `include` option, for example;
+    // is there a compelling use-case?), this would actually be testable
     if (!versionFound) {
         throw new Error(`Unexpected error: Markdown file at "${filePath}" does not belong to any docs version!`);
     }

package/lib/numberPrefix.js

@@ -8,33 +8,28 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.stripPathNumberPrefixes = exports.stripNumberPrefix = exports.DisabledNumberPrefixParser = exports.DefaultNumberPrefixParser = void 0;
 // Best-effort to avoid parsing some patterns as number prefix
-const IgnoredPrefixPatterns = (() => {
-    // ignore common date-like patterns: https://github.com/facebook/docusaurus/issues/4640
-    const DateLikePrefixRegex = /^(?:\d{2}|\d{4})[-_.]\d{2}(?:[-_.](?:\d{2}|\d{4}))?.*$/;
-    // ignore common versioning patterns: https://github.com/facebook/docusaurus/issues/4653
-    // note: we could try to parse float numbers in filenames but that is
-    // probably not worth it as a version such as "8.0" can be interpreted as both
-    // a version and a float. User can configure her own NumberPrefixParser if
-    // she wants 8.0 to be interpreted as a float
-    const VersionLikePrefixRegex = /^\d+[-_.]\d+.*$/;
-    return new RegExp(`${DateLikePrefixRegex.source}|${VersionLikePrefixRegex.source}`);
-})();
-const NumberPrefixRegex = /^(?<numberPrefix>\d+)(?<separator>\s*[-_.]+\s*)(?<suffix>.*)$/;
+// ignore common date-like patterns: https://github.com/facebook/docusaurus/issues/4640
+// ignore common versioning patterns: https://github.com/facebook/docusaurus/issues/4653
+// Both of them would look like 7.0-foo or 2021-11-foo
+// note: we could try to parse float numbers in filenames, but that is probably
+// not worth it, as a version such as "8.0" can be interpreted as either a
+// version or a float. User can configure her own NumberPrefixParser if she
+// wants 8.0 to be interpreted as a float
+const ignoredPrefixPattern = /^\d+[-_.]\d+/;
+const numberPrefixPattern = /^(?<numberPrefix>\d+)\s*[-_.]+\s*(?<suffix>[^-_.\s].*)$/;
 // 0-myDoc => {filename: myDoc, numberPrefix: 0}
 // 003 - myDoc => {filename: myDoc, numberPrefix: 3}
 const DefaultNumberPrefixParser = (filename) => {
-    if (IgnoredPrefixPatterns.exec(filename)) {
+    if (ignoredPrefixPattern.test(filename)) {
+        return { filename, numberPrefix: undefined };
+    }
+    const match = numberPrefixPattern.exec(filename);
+    if (!match) {
         return { filename, numberPrefix: undefined };
     }
-    const match = NumberPrefixRegex.exec(filename);
-    const cleanFileName = match?.groups?.suffix ?? filename;
-    const numberPrefixString = match?.groups?.numberPrefix;
-    const numberPrefix = numberPrefixString
-        ? parseInt(numberPrefixString, 10)
-        : undefined;
     return {
-        filename: cleanFileName,
-        numberPrefix,
+        filename: match.groups.suffix,
+        numberPrefix: parseInt(match.groups.numberPrefix, 10),
     };
 };
 exports.DefaultNumberPrefixParser = DefaultNumberPrefixParser;

package/lib/options.d.ts

@@ -4,9 +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 '@docusaurus/plugin-content-docs';
-import { Joi } from '@docusaurus/utils-validation';
-import type { OptionValidationContext, ValidationResult } from '@docusaurus/types';
+import type { PluginOptions, Options } from '@docusaurus/plugin-content-docs';
+import type { OptionValidationContext } from '@docusaurus/types';
 export declare const DEFAULT_OPTIONS: Omit<PluginOptions, 'id' | 'sidebarPath'>;
-export declare const OptionsSchema: Joi.ObjectSchema<any>;
-export declare function validateOptions({ validate, options: userOptions, }: OptionValidationContext<PluginOptions>): ValidationResult<PluginOptions>;
+export declare function validateOptions({ validate, options: userOptions, }: OptionValidationContext<Options, PluginOptions>): PluginOptions;

package/lib/options.js

@@ -6,7 +6,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.validateOptions = exports.OptionsSchema = exports.DEFAULT_OPTIONS = void 0;
+exports.validateOptions = exports.DEFAULT_OPTIONS = void 0;
 const tslib_1 = require("tslib");
 const utils_validation_1 = require("@docusaurus/utils-validation");
 const utils_1 = require("@docusaurus/utils");
@@ -54,7 +54,7 @@ const VersionOptionsSchema = utils_validation_1.Joi.object({
 const VersionsOptionsSchema = utils_validation_1.Joi.object()
     .pattern(utils_validation_1.Joi.string().required(), VersionOptionsSchema)
     .default(exports.DEFAULT_OPTIONS.versions);
-exports.OptionsSchema = utils_validation_1.Joi.object({
+const OptionsSchema = utils_validation_1.Joi.object({
     path: utils_validation_1.Joi.string().default(exports.DEFAULT_OPTIONS.path),
     editUrl: utils_validation_1.Joi.alternatives().try(utils_validation_1.URISchema, utils_validation_1.Joi.function()),
     editCurrentVersion: utils_validation_1.Joi.boolean().default(exports.DEFAULT_OPTIONS.editCurrentVersion),
@@ -64,6 +64,7 @@ exports.OptionsSchema = utils_validation_1.Joi.object({
         // .allow('') ""
         .default(exports.DEFAULT_OPTIONS.routeBasePath),
     tagsBasePath: utils_validation_1.Joi.string().default(exports.DEFAULT_OPTIONS.tagsBasePath),
+    // @ts-expect-error: deprecated
     homePageId: utils_validation_1.Joi.any().forbidden().messages({
         'any.unknown': 'The docs plugin option homePageId is not supported anymore. To make a doc the "home", please add "slug: /" in its front matter. See: https://docusaurus.io/docs/next/docs-introduction#home-page-docs',
     }),
@@ -121,7 +122,7 @@ function validateOptions({ validate, options: userOptions, }) {
             };
         }
     }
-    const normalizedOptions = validate(exports.OptionsSchema, options);
+    const normalizedOptions = validate(OptionsSchema, options);
     if (normalizedOptions.admonitions) {
         normalizedOptions.remarkPlugins = normalizedOptions.remarkPlugins.concat([
             [remark_admonitions_1.default, normalizedOptions.admonitions],

package/lib/sidebars/generator.js

@@ -27,7 +27,9 @@ const DefaultSidebarItemsGenerator = async ({ numberPrefixParser, isCategoryInde
     const getDoc = (docId) => {
         const doc = findDoc(docId);
         if (!doc) {
-            throw new Error(`Can't find any doc with id=${docId}.\nAvailable doc ids:\n- ${Object.keys(docsById).join('\n- ')}`);
+            throw new Error(`Can't find any doc with ID ${docId}.
+Available doc IDs:
+- ${Object.keys(docsById).join('\n- ')}`);
         }
         return doc;
     };
@@ -103,8 +105,6 @@ const DefaultSidebarItemsGenerator = async ({ numberPrefixParser, isCategoryInde
         }
         function createCategoryItem(dir, fullPath, folderName) {
             const categoryMetadata = categoriesMetadata[(0, utils_1.posixPath)(path_1.default.join(autogenDir, fullPath))];
-            const className = categoryMetadata?.className;
-            const { filename, numberPrefix } = numberPrefixParser(folderName);
             const allItems = Object.entries(dir).map(([key, content]) => dirToItem(content, key, `${fullPath}/${key}`));
             // Try to match a doc inside the category folder,
             // using the "local id" (myDoc) or "qualified id" (dirName/myDoc)
@@ -120,35 +120,51 @@ const DefaultSidebarItemsGenerator = async ({ numberPrefixParser, isCategoryInde
                     return isCategoryIndex((0, docs_1.toCategoryIndexMatcherParam)(doc));
                 });
             }
-            function getCategoryLinkedDocId() {
+            // In addition to the ID, this function also retrieves metadata of the
+            // linked doc that could be used as fallback values for category metadata
+            function getCategoryLinkedDocMetadata() {
                 const link = categoryMetadata?.link;
-                if (link !== undefined) {
-                    if (link && link.type === 'doc') {
-                        return findDocByLocalId(link.id)?.id || getDoc(link.id).id;
-                    }
+                if (link !== undefined && link?.type !== 'doc') {
                     // If a link is explicitly specified, we won't apply conventions
                     return undefined;
                 }
-                // Apply default convention to pick index.md, README.md or
-                // <categoryName>.md as the category doc
-                return findConventionalCategoryDocLink()?.id;
+                const id = link
+                    ? findDocByLocalId(link.id)?.id ?? getDoc(link.id).id
+                    : findConventionalCategoryDocLink()?.id;
+                if (!id) {
+                    return undefined;
+                }
+                const doc = getDoc(id);
+                return {
+                    id,
+                    position: doc.sidebarPosition,
+                    label: doc.frontMatter.sidebar_label ?? doc.title,
+                    customProps: doc.frontMatter.sidebar_custom_props,
+                    className: doc.frontMatter.sidebar_class_name,
+                };
             }
-            const categoryLinkedDocId = getCategoryLinkedDocId();
-            const link = categoryLinkedDocId
+            const categoryLinkedDoc = getCategoryLinkedDocMetadata();
+            const link = categoryLinkedDoc
                 ? {
                     type: 'doc',
-                    id: categoryLinkedDocId, // We "remap" a potentially "local id" to a "qualified id"
+                    id: categoryLinkedDoc.id, // We "remap" a potentially "local id" to a "qualified id"
                 }
                 : categoryMetadata?.link;
             // If a doc is linked, remove it from the category subItems
-            const items = allItems.filter((item) => !(item.type === 'doc' && item.id === categoryLinkedDocId));
+            const items = allItems.filter((item) => !(item.type === 'doc' && item.id === categoryLinkedDoc?.id));
+            const className = categoryMetadata?.className ?? categoryLinkedDoc?.className;
+            const customProps = categoryMetadata?.customProps ?? categoryLinkedDoc?.customProps;
+            const { filename, numberPrefix } = numberPrefixParser(folderName);
             return {
                 type: 'category',
-                label: categoryMetadata?.label ?? filename,
+                label: categoryMetadata?.label ?? categoryLinkedDoc?.label ?? filename,
                 collapsible: categoryMetadata?.collapsible,
                 collapsed: categoryMetadata?.collapsed,
-                position: categoryMetadata?.position ?? numberPrefix,
+                position: categoryMetadata?.position ??
+                    categoryLinkedDoc?.position ??
+                    numberPrefix,
                 source: folderName,
+                ...(customProps !== undefined && { customProps }),
                 ...(className !== undefined && { className }),
                 items,
                 ...(link && { link }),

package/lib/sidebars/index.js

@@ -43,7 +43,7 @@ async function readCategoriesMetadata(contentPath) {
     });
     const categoryToFile = lodash_1.default.groupBy(categoryFiles, path_1.default.dirname);
     return (0, combine_promises_1.default)(lodash_1.default.mapValues(categoryToFile, async (files, folder) => {
-        const [filePath] = files;
+        const filePath = files[0];
         if (files.length > 1) {
             logger_1.default.warn `There are more than one category metadata files for path=${folder}: ${files.join(', ')}. The behavior is undetermined.`;
         }
@@ -78,11 +78,17 @@ async function loadSidebarsFileUnsafe(sidebarFilePath) {
 exports.loadSidebarsFileUnsafe = loadSidebarsFileUnsafe;
 // Note: sidebarFilePath must be absolute, use resolveSidebarPathOption
 async function loadSidebars(sidebarFilePath, options) {
-    const sidebarsConfig = await loadSidebarsFileUnsafe(sidebarFilePath);
-    const normalizedSidebars = (0, normalization_1.normalizeSidebars)(sidebarsConfig);
-    (0, validation_1.validateSidebars)(normalizedSidebars);
-    const categoriesMetadata = await readCategoriesMetadata(options.version.contentPath);
-    const processedSidebars = await (0, processor_1.processSidebars)(normalizedSidebars, categoriesMetadata, options);
-    return (0, postProcessor_1.postProcessSidebars)(processedSidebars, options);
+    try {
+        const sidebarsConfig = await loadSidebarsFileUnsafe(sidebarFilePath);
+        const normalizedSidebars = (0, normalization_1.normalizeSidebars)(sidebarsConfig);
+        (0, validation_1.validateSidebars)(normalizedSidebars);
+        const categoriesMetadata = await readCategoriesMetadata(options.version.contentPath);
+        const processedSidebars = await (0, processor_1.processSidebars)(normalizedSidebars, categoriesMetadata, options);
+        return (0, postProcessor_1.postProcessSidebars)(processedSidebars, options);
+    }
+    catch (err) {
+        logger_1.default.error `Sidebars file at path=${sidebarFilePath} failed to be loaded.`;
+        throw err;
+    }
 }
 exports.loadSidebars = loadSidebars;

package/lib/sidebars/postProcessor.js

@@ -39,22 +39,17 @@ function postProcessSidebarItem(item, params) {
             if (!category.link) {
                 throw new Error(`Sidebar category ${item.label} has neither any subitem nor a link. This makes this item not able to link to anything.`);
             }
-            switch (category.link.type) {
-                case 'doc':
-                    return {
-                        type: 'doc',
-                        label: category.label,
-                        id: category.link.id,
-                    };
-                case 'generated-index':
-                    return {
-                        type: 'link',
-                        label: category.label,
-                        href: category.link.permalink,
-                    };
-                default:
-                    throw new Error('Unexpected sidebar category link type');
-            }
+            return category.link.type === 'doc'
+                ? {
+                    type: 'doc',
+                    label: category.label,
+                    id: category.link.id,
+                }
+                : {
+                    type: 'link',
+                    label: category.label,
+                    href: category.link.permalink,
+                };
         }
         // A non-collapsible category can't be collapsed!
         if (category.collapsible === false) {

package/lib/sidebars/processor.d.ts

@@ -5,4 +5,6 @@
  * LICENSE file in the root directory of this source tree.
  */
 import type { NormalizedSidebars, ProcessedSidebars, SidebarProcessorParams, CategoryMetadataFile } from './types';
-export declare function processSidebars(unprocessedSidebars: NormalizedSidebars, categoriesMetadata: Record<string, CategoryMetadataFile>, params: SidebarProcessorParams): Promise<ProcessedSidebars>;
+export declare function processSidebars(unprocessedSidebars: NormalizedSidebars, categoriesMetadata: {
+    [filePath: string]: CategoryMetadataFile;
+}, params: SidebarProcessorParams): Promise<ProcessedSidebars>;

package/lib/sidebars/processor.js

@@ -17,6 +17,7 @@ function toSidebarItemsGeneratorDoc(doc) {
     return lodash_1.default.pick(doc, [
         'id',
         'unversionedId',
+        'title',
         'frontMatter',
         'source',
         'sourceDirName',
@@ -29,7 +30,7 @@ function toSidebarItemsGeneratorVersion(version) {
 // Handle the generation of autogenerated sidebar items and other
 // post-processing checks
 async function processSidebar(unprocessedSidebar, categoriesMetadata, params) {
-    const { sidebarItemsGenerator, numberPrefixParser, docs, version, sidebarOptions, } = params;
+    const { sidebarItemsGenerator, numberPrefixParser, docs, version } = params;
     // Just a minor lazy transformation optimization
     const getSidebarItemsGeneratorDocsAndVersion = lodash_1.default.memoize(() => ({
         docs: docs.map(toSidebarItemsGeneratorDoc),
@@ -42,7 +43,6 @@ async function processSidebar(unprocessedSidebar, categoriesMetadata, params) {
             defaultSidebarItemsGenerator: generator_1.DefaultSidebarItemsGenerator,
             isCategoryIndex: docs_1.isCategoryIndex,
             ...getSidebarItemsGeneratorDocsAndVersion(),
-            options: sidebarOptions,
             categoriesMetadata,
         });
         // Process again... weird but sidebar item generated might generate some