@docusaurus/plugin-content-docs 0.0.0-4539 → 0.0.0-4545

package/lib/lastUpdate.js

@@ -10,6 +10,7 @@ exports.getFileLastUpdate = void 0;
 const tslib_1 = require("tslib");
 const shelljs_1 = (0, tslib_1.__importDefault)(require("shelljs"));
 const logger_1 = (0, tslib_1.__importDefault)(require("@docusaurus/logger"));
+const path_1 = (0, tslib_1.__importDefault)(require("path"));
 const GIT_COMMIT_TIMESTAMP_AUTHOR_REGEX = /^(?<timestamp>\d+),(?<author>.+)$/;
 let showedGitRequirementError = false;
 async function getFileLastUpdate(filePath) {
@@ -36,7 +37,13 @@ async function getFileLastUpdate(filePath) {
             }
             return null;
         }
-        const result = shelljs_1.default.exec(`git log -1 --format=%ct,%an "${filePath}"`, {
+        if (!shelljs_1.default.test('-f', filePath)) {
+            throw new Error(`Retrieval of git history failed at "${filePath}" because the file does not exist.`);
+        }
+        const fileBasename = path_1.default.basename(filePath);
+        const fileDirname = path_1.default.dirname(filePath);
+        const result = shelljs_1.default.exec(`git log --max-count=1 --format=%ct,%an -- "${fileBasename}"`, {
+            cwd: fileDirname,
             silent: true,
         });
         if (result.code !== 0) {

package/lib/sidebars/generator.d.ts

@@ -4,15 +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 { SidebarItemsGenerator, SidebarItemCategoryLinkConfig } from './types';
+import type { SidebarItemsGenerator } from './types';
 export declare const CategoryMetadataFilenameBase = "_category_";
 export declare const CategoryMetadataFilenamePattern = "_category_.{json,yml,yaml}";
-export declare type CategoryMetadataFile = {
-    label?: string;
-    position?: number;
-    collapsed?: boolean;
-    collapsible?: boolean;
-    className?: string;
-    link?: SidebarItemCategoryLinkConfig | null;
-};
 export declare const DefaultSidebarItemsGenerator: SidebarItemsGenerator;

package/lib/sidebars/generator.js

@@ -12,9 +12,6 @@ const lodash_1 = require("lodash");
 const utils_1 = require("@docusaurus/utils");
 const logger_1 = (0, tslib_1.__importDefault)(require("@docusaurus/logger"));
 const path_1 = (0, tslib_1.__importDefault)(require("path"));
-const fs_extra_1 = (0, tslib_1.__importDefault)(require("fs-extra"));
-const js_yaml_1 = (0, tslib_1.__importDefault)(require("js-yaml"));
-const validation_1 = require("./validation");
 const docs_1 = require("../docs");
 const BreadcrumbSeparator = '/';
 // To avoid possible name clashes with a folder of the same name as the ID
@@ -25,30 +22,8 @@ function getLocalDocId(docId) {
 }
 exports.CategoryMetadataFilenameBase = '_category_';
 exports.CategoryMetadataFilenamePattern = '_category_.{json,yml,yaml}';
-// TODO I now believe we should read all the category metadata files ahead of
-// time: we may need this metadata to customize docs metadata
-// Example use-case being able to disable number prefix parsing at the folder
-// level, or customize the default base slug for an intermediate directory
-// TODO later if there is `CategoryFolder/with-category-name-doc.md`, we may
-// want to read the metadata as yaml on it
-// see https://github.com/facebook/docusaurus/issues/3464#issuecomment-818670449
-async function readCategoryMetadataFile(categoryDirPath) {
-    async function tryReadFile(filePath) {
-        const contentString = await fs_extra_1.default.readFile(filePath, { encoding: 'utf8' });
-        const unsafeContent = js_yaml_1.default.load(contentString);
-        try {
-            return (0, validation_1.validateCategoryMetadataFile)(unsafeContent);
-        }
-        catch (e) {
-            logger_1.default.error `The docs sidebar category metadata file path=${filePath} looks invalid!`;
-            throw e;
-        }
-    }
-    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, isCategoryIndex, docs: allDocs, options, item: { dirName: autogenDir }, version, }) => {
+const DefaultSidebarItemsGenerator = async ({ numberPrefixParser, isCategoryIndex, docs: allDocs, options, item: { dirName: autogenDir }, categoriesMetadata, }) => {
     const docsById = (0, docs_1.createDocsByIdIndex)(allDocs);
     const findDoc = (docId) => docsById[docId];
     const getDoc = (docId) => {
@@ -127,8 +102,7 @@ const DefaultSidebarItemsGenerator = async ({ numberPrefixParser, isCategoryInde
         }
         async function createCategoryItem(dir, fullPath, folderName) {
             var _a, _b, _c, _d;
-            const categoryPath = path_1.default.join(version.contentPath, autogenDir, fullPath);
-            const categoryMetadata = await readCategoryMetadataFile(categoryPath);
+            const categoryMetadata = categoriesMetadata[(0, utils_1.posixPath)(path_1.default.join(autogenDir, fullPath))];
             const className = categoryMetadata === null || categoryMetadata === void 0 ? void 0 : categoryMetadata.className;
             const { filename, numberPrefix } = numberPrefixParser(folderName);
             const allItems = await Promise.all(Object.entries(dir).map(([key, content]) => dirToItem(content, key, `${fullPath}/${key}`)));

package/lib/sidebars/index.d.ts

@@ -13,4 +13,4 @@ export declare const DisabledSidebars: SidebarsConfig;
 export declare function resolveSidebarPathOption(siteDir: string, sidebarPathOption: PluginOptions['sidebarPath']): PluginOptions['sidebarPath'];
 export declare function loadSidebarsFile(sidebarFilePath: string | false | undefined): Promise<SidebarsConfig>;
 export declare function loadNormalizedSidebars(sidebarFilePath: string | false | undefined, params: NormalizeSidebarsParams): Promise<NormalizedSidebars>;
-export declare function loadSidebars(sidebarFilePath: string | false | undefined, options: SidebarProcessorParams): Promise<Sidebars>;
+export declare function loadSidebars(sidebarFilePath: string | false | undefined, options: Omit<SidebarProcessorParams, 'categoriesMetadata'>): Promise<Sidebars>;

package/lib/sidebars/index.js

@@ -15,6 +15,10 @@ const normalization_1 = require("./normalization");
 const processor_1 = require("./processor");
 const path_1 = (0, tslib_1.__importDefault)(require("path"));
 const utils_1 = require("@docusaurus/utils");
+const logger_1 = (0, tslib_1.__importDefault)(require("@docusaurus/logger"));
+const js_yaml_1 = (0, tslib_1.__importDefault)(require("js-yaml"));
+const lodash_1 = require("lodash");
+const combine_promises_1 = (0, tslib_1.__importDefault)(require("combine-promises"));
 exports.DefaultSidebars = {
     defaultSidebar: [
         {
@@ -32,6 +36,26 @@ function resolveSidebarPathOption(siteDir, sidebarPathOption) {
         : sidebarPathOption;
 }
 exports.resolveSidebarPathOption = resolveSidebarPathOption;
+async function readCategoriesMetadata(contentPath) {
+    const categoryFiles = await (0, utils_1.Globby)('**/_category_.{json,yml,yaml}', {
+        cwd: contentPath,
+    });
+    const categoryToFile = (0, lodash_1.groupBy)(categoryFiles, path_1.default.dirname);
+    return (0, combine_promises_1.default)((0, lodash_1.mapValues)(categoryToFile, async (files, folder) => {
+        const [filePath] = files;
+        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.`;
+        }
+        const content = await fs_extra_1.default.readFile(path_1.default.join(contentPath, filePath), 'utf-8');
+        try {
+            return (0, validation_1.validateCategoryMetadataFile)(js_yaml_1.default.load(content));
+        }
+        catch (e) {
+            logger_1.default.error `The docs sidebar category metadata file path=${filePath} looks invalid!`;
+            throw e;
+        }
+    }));
+}
 async function loadSidebarsFileUnsafe(sidebarFilePath) {
     // false => no sidebars
     if (sidebarFilePath === false) {
@@ -68,6 +92,7 @@ async function loadSidebars(sidebarFilePath, options) {
         categoryLabelSlugger: (0, utils_1.createSlugger)(),
     };
     const normalizedSidebars = await loadNormalizedSidebars(sidebarFilePath, normalizeSidebarsParams);
-    return (0, processor_1.processSidebars)(normalizedSidebars, options);
+    const categoriesMetadata = await readCategoriesMetadata(options.version.contentPath);
+    return (0, processor_1.processSidebars)(normalizedSidebars, { ...options, categoriesMetadata });
 }
 exports.loadSidebars = loadSidebars;

package/lib/sidebars/processor.d.ts

@@ -5,7 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 import type { DocMetadataBase, VersionMetadata } from '../types';
-import type { Sidebars, NormalizedSidebars, SidebarItemsGeneratorOption } from './types';
+import type { Sidebars, NormalizedSidebars, SidebarItemsGeneratorOption, CategoryMetadataFile } from './types';
 import type { Slugger } from '@docusaurus/utils';
 import type { NumberPrefixParser, SidebarOptions } from '@docusaurus/plugin-content-docs';
 export declare type SidebarProcessorParams = {
@@ -15,5 +15,6 @@ export declare type SidebarProcessorParams = {
     version: VersionMetadata;
     categoryLabelSlugger: Slugger;
     sidebarOptions: SidebarOptions;
+    categoriesMetadata: Record<string, CategoryMetadataFile>;
 };
 export declare function processSidebars(unprocessedSidebars: NormalizedSidebars, params: SidebarProcessorParams): Promise<Sidebars>;

package/lib/sidebars/processor.js

@@ -30,7 +30,7 @@ function toSidebarItemsGeneratorVersion(version) {
 // Handle the generation of autogenerated sidebar items and other
 // post-processing checks
 async function processSidebar(unprocessedSidebar, params) {
-    const { sidebarItemsGenerator, numberPrefixParser, docs, version, sidebarOptions, } = params;
+    const { sidebarItemsGenerator, numberPrefixParser, docs, version, sidebarOptions, categoriesMetadata, } = params;
     // Just a minor lazy transformation optimization
     const getSidebarItemsGeneratorDocsAndVersion = (0, lodash_1.memoize)(() => ({
         docs: docs.map(toSidebarItemsGeneratorDoc),
@@ -52,6 +52,7 @@ async function processSidebar(unprocessedSidebar, params) {
             isCategoryIndex: docs_1.isCategoryIndex,
             ...getSidebarItemsGeneratorDocsAndVersion(),
             options: sidebarOptions,
+            categoriesMetadata,
         });
         // TODO validate generated items: user can generate bad items
         const generatedItemsNormalized = generatedItems.flatMap((generatedItem) => (0, normalization_1.normalizeItem)(generatedItem, { ...params, ...sidebarOptions }));

package/lib/sidebars/types.d.ts

@@ -19,6 +19,11 @@ export declare type SidebarItemDoc = SidebarItemBase & {
     label?: string;
     id: string;
 };
+export declare type SidebarItemHtml = SidebarItemBase & {
+    type: 'html';
+    value: string;
+    defaultStyle?: boolean;
+};
 export declare type SidebarItemLink = SidebarItemBase & {
     type: 'link';
     href: string;
@@ -64,7 +69,7 @@ export declare type SidebarItemCategoryConfig = Expand<Optional<SidebarItemCateg
 export declare type SidebarCategoriesShorthand = {
     [sidebarCategory: string]: SidebarItemConfig[];
 };
-export declare type SidebarItemConfig = SidebarItemDoc | SidebarItemLink | SidebarItemAutogenerated | SidebarItemCategoryConfig | string | SidebarCategoriesShorthand;
+export declare type SidebarItemConfig = SidebarItemDoc | SidebarItemHtml | SidebarItemLink | SidebarItemAutogenerated | SidebarItemCategoryConfig | string | SidebarCategoriesShorthand;
 export declare type SidebarConfig = SidebarCategoriesShorthand | SidebarItemConfig[];
 export declare type SidebarsConfig = {
     [sidebarId: string]: SidebarConfig;
@@ -73,7 +78,7 @@ export declare type NormalizedSidebarItemCategory = Expand<SidebarItemCategoryBa
     items: NormalizedSidebarItem[];
     link?: SidebarItemCategoryLink;
 }>;
-export declare type NormalizedSidebarItem = SidebarItemDoc | SidebarItemLink | NormalizedSidebarItemCategory | SidebarItemAutogenerated;
+export declare type NormalizedSidebarItem = SidebarItemDoc | SidebarItemHtml | SidebarItemLink | NormalizedSidebarItemCategory | SidebarItemAutogenerated;
 export declare type NormalizedSidebar = NormalizedSidebarItem[];
 export declare type NormalizedSidebars = {
     [sidebarId: string]: NormalizedSidebar;
@@ -86,7 +91,7 @@ export declare type SidebarItemCategoryWithLink = Required<SidebarItemCategory,
 export declare type SidebarItemCategoryWithGeneratedIndex = SidebarItemCategoryWithLink & {
     link: SidebarItemCategoryLinkGeneratedIndex;
 };
-export declare type SidebarItem = SidebarItemDoc | SidebarItemLink | SidebarItemCategory;
+export declare type SidebarItem = SidebarItemDoc | SidebarItemHtml | SidebarItemLink | SidebarItemCategory;
 export declare type SidebarNavigationItem = SidebarItemDoc | SidebarItemCategoryWithLink;
 export declare type Sidebar = SidebarItem[];
 export declare type SidebarItemType = SidebarItem['type'];
@@ -100,7 +105,8 @@ export declare type PropSidebarItemCategory = Expand<SidebarItemCategoryBase & {
 export declare type PropSidebarItemLink = SidebarItemLink & {
     docId?: string;
 };
-export declare type PropSidebarItem = PropSidebarItemLink | PropSidebarItemCategory;
+export declare type PropSidebarItemHtml = SidebarItemHtml;
+export declare type PropSidebarItem = PropSidebarItemLink | PropSidebarItemCategory | PropSidebarItemHtml;
 export declare type PropSidebar = PropSidebarItem[];
 export declare type PropSidebars = {
     [sidebarId: string]: PropSidebar;
@@ -114,6 +120,14 @@ export declare type PropVersionDoc = {
 export declare type PropVersionDocs = {
     [docId: string]: PropVersionDoc;
 };
+export declare type CategoryMetadataFile = {
+    label?: string;
+    position?: number;
+    collapsed?: boolean;
+    collapsible?: boolean;
+    className?: string;
+    link?: SidebarItemCategoryLinkConfig | null;
+};
 export declare type SidebarItemsGeneratorDoc = Pick<DocMetadataBase, 'id' | 'unversionedId' | 'frontMatter' | 'source' | 'sourceDirName' | 'sidebarPosition'>;
 export declare type SidebarItemsGeneratorVersion = Pick<VersionMetadata, 'versionName' | 'contentPath'>;
 export declare type SidebarItemsGeneratorArgs = {
@@ -122,6 +136,7 @@ export declare type SidebarItemsGeneratorArgs = {
     docs: SidebarItemsGeneratorDoc[];
     numberPrefixParser: NumberPrefixParser;
     isCategoryIndex: CategoryIndexMatcher;
+    categoriesMetadata: Record<string, CategoryMetadataFile>;
     options: SidebarOptions;
 };
 export declare type SidebarItemsGenerator = (generatorArgs: SidebarItemsGeneratorArgs) => Promise<SidebarItem[]>;

package/lib/sidebars/validation.d.ts

@@ -4,7 +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 { SidebarsConfig } from './types';
-import type { CategoryMetadataFile } from './generator';
+import type { SidebarsConfig, CategoryMetadataFile } from './types';
 export declare function validateSidebars(sidebars: unknown): asserts sidebars is SidebarsConfig;
 export declare function validateCategoryMetadataFile(unsafeContent: unknown): CategoryMetadataFile;

package/lib/sidebars/validation.js

@@ -28,6 +28,11 @@ const sidebarItemDocSchema = sidebarItemBaseSchema.append({
     id: utils_validation_1.Joi.string().required(),
     label: utils_validation_1.Joi.string(),
 });
+const sidebarItemHtmlSchema = sidebarItemBaseSchema.append({
+    type: 'html',
+    value: utils_validation_1.Joi.string().required(),
+    defaultStyle: utils_validation_1.Joi.boolean().default(false),
+});
 const sidebarItemLinkSchema = sidebarItemBaseSchema.append({
     type: 'link',
     href: utils_validation_1.URISchema.required(),
@@ -93,6 +98,7 @@ const sidebarItemSchema = utils_validation_1.Joi.object()
             is: utils_validation_1.Joi.string().valid('doc', 'ref').required(),
             then: sidebarItemDocSchema,
         },
+        { is: 'html', then: sidebarItemHtmlSchema },
         { is: 'autogenerated', then: sidebarItemAutogeneratedSchema },
         { is: 'category', then: sidebarItemCategorySchema },
         {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/plugin-content-docs",
-  "version": "0.0.0-4539",
+  "version": "0.0.0-4545",
   "description": "Docs plugin for Docusaurus.",
   "main": "lib/index.js",
   "exports": {
@@ -23,11 +23,11 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/core": "0.0.0-4539",
-    "@docusaurus/logger": "0.0.0-4539",
-    "@docusaurus/mdx-loader": "0.0.0-4539",
-    "@docusaurus/utils": "0.0.0-4539",
-    "@docusaurus/utils-validation": "0.0.0-4539",
+    "@docusaurus/core": "0.0.0-4545",
+    "@docusaurus/logger": "0.0.0-4545",
+    "@docusaurus/mdx-loader": "0.0.0-4545",
+    "@docusaurus/utils": "0.0.0-4545",
+    "@docusaurus/utils-validation": "0.0.0-4545",
     "combine-promises": "^1.1.0",
     "fs-extra": "^10.0.0",
     "import-fresh": "^3.2.2",
@@ -40,8 +40,8 @@
     "webpack": "^5.68.0"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "0.0.0-4539",
-    "@docusaurus/types": "0.0.0-4539",
+    "@docusaurus/module-type-aliases": "0.0.0-4545",
+    "@docusaurus/types": "0.0.0-4545",
     "@types/js-yaml": "^4.0.0",
     "@types/picomatch": "^2.2.1",
     "commander": "^5.1.0",
@@ -57,5 +57,5 @@
   "engines": {
     "node": ">=14"
   },
-  "gitHead": "7b82719906447f76637ad0452ad8df1d9698f805"
+  "gitHead": "2fd48f443b78b58b3b511f797a0050d407370f07"
 }

package/src/lastUpdate.ts

@@ -7,6 +7,7 @@
 
 import shell from 'shelljs';
 import logger from '@docusaurus/logger';
+import path from 'path';
 
 type FileLastUpdateData = {timestamp?: number; author?: string};
 
@@ -43,9 +44,21 @@ export async function getFileLastUpdate(
       return null;
     }
 
-    const result = shell.exec(`git log -1 --format=%ct,%an "${filePath}"`, {
-      silent: true,
-    });
+    if (!shell.test('-f', filePath)) {
+      throw new Error(
+        `Retrieval of git history failed at "${filePath}" because the file does not exist.`,
+      );
+    }
+
+    const fileBasename = path.basename(filePath);
+    const fileDirname = path.dirname(filePath);
+    const result = shell.exec(
+      `git log --max-count=1 --format=%ct,%an -- "${fileBasename}"`,
+      {
+        cwd: fileDirname, // this is needed: https://github.com/facebook/docusaurus/pull/5048
+        silent: true,
+      },
+    );
     if (result.code !== 0) {
       throw new Error(
         `Retrieval of git history failed at "${filePath}" with exit code ${result.code}: ${result.stderr}`,

package/src/sidebars/generator.ts

@@ -12,19 +12,11 @@ import type {
   SidebarItemsGenerator,
   SidebarItemsGeneratorDoc,
   SidebarItemCategoryLink,
-  SidebarItemCategoryLinkConfig,
 } from './types';
 import {sortBy, last} from 'lodash';
-import {
-  addTrailingSlash,
-  posixPath,
-  findAsyncSequential,
-} from '@docusaurus/utils';
+import {addTrailingSlash, posixPath} from '@docusaurus/utils';
 import logger from '@docusaurus/logger';
 import path from 'path';
-import fs from 'fs-extra';
-import Yaml from 'js-yaml';
-import {validateCategoryMetadataFile} from './validation';
 import {createDocsByIdIndex, toCategoryIndexMatcherParam} from '../docs';
 
 const BreadcrumbSeparator = '/';
@@ -39,20 +31,6 @@ function getLocalDocId(docId: string): string {
 export const CategoryMetadataFilenameBase = '_category_';
 export const CategoryMetadataFilenamePattern = '_category_.{json,yml,yaml}';
 
-export type CategoryMetadataFile = {
-  label?: string;
-  position?: number;
-  collapsed?: boolean;
-  collapsible?: boolean;
-  className?: string;
-  link?: SidebarItemCategoryLinkConfig | null;
-
-  // TODO should we allow "items" here? how would this work? would an
-  // "autogenerated" type be allowed?
-  // This mkdocs plugin do something like that: https://github.com/lukasgeiter/mkdocs-awesome-pages-plugin/
-  // cf comment: https://github.com/facebook/docusaurus/issues/3464#issuecomment-784765199
-};
-
 type WithPosition<T> = T & {position?: number};
 
 /**
@@ -65,37 +43,6 @@ type Dir = {
   [item: string]: Dir | null;
 };
 
-// TODO I now believe we should read all the category metadata files ahead of
-// time: we may need this metadata to customize docs metadata
-// Example use-case being able to disable number prefix parsing at the folder
-// level, or customize the default base slug for an intermediate directory
-// TODO later if there is `CategoryFolder/with-category-name-doc.md`, we may
-// want to read the metadata as yaml on it
-// see https://github.com/facebook/docusaurus/issues/3464#issuecomment-818670449
-async function readCategoryMetadataFile(
-  categoryDirPath: string,
-): Promise<CategoryMetadataFile | null> {
-  async function tryReadFile(filePath: string): Promise<CategoryMetadataFile> {
-    const contentString = await fs.readFile(filePath, {encoding: 'utf8'});
-    const unsafeContent = Yaml.load(contentString);
-    try {
-      return validateCategoryMetadataFile(unsafeContent);
-    } catch (e) {
-      logger.error`The docs sidebar category metadata file path=${filePath} looks invalid!`;
-      throw e;
-    }
-  }
-  const filePath = await findAsyncSequential(
-    ['.json', '.yml', '.yaml'].map((ext) =>
-      posixPath(
-        path.join(categoryDirPath, `${CategoryMetadataFilenameBase}${ext}`),
-      ),
-    ),
-    fs.pathExists,
-  );
-  return filePath ? tryReadFile(filePath) : null;
-}
-
 // Comment for this feature: https://github.com/facebook/docusaurus/issues/3464#issuecomment-818670449
 export const DefaultSidebarItemsGenerator: SidebarItemsGenerator = async ({
   numberPrefixParser,
@@ -103,7 +50,7 @@ export const DefaultSidebarItemsGenerator: SidebarItemsGenerator = async ({
   docs: allDocs,
   options,
   item: {dirName: autogenDir},
-  version,
+  categoriesMetadata,
 }) => {
   const docsById = createDocsByIdIndex(allDocs);
   const findDoc = (docId: string): SidebarItemsGeneratorDoc | undefined =>
@@ -199,8 +146,8 @@ export const DefaultSidebarItemsGenerator: SidebarItemsGenerator = async ({
       fullPath: string,
       folderName: string,
     ): Promise<WithPosition<SidebarItemCategory>> {
-      const categoryPath = path.join(version.contentPath, autogenDir, fullPath);
-      const categoryMetadata = await readCategoryMetadataFile(categoryPath);
+      const categoryMetadata =
+        categoriesMetadata[posixPath(path.join(autogenDir, fullPath))];
       const className = categoryMetadata?.className;
       const {filename, numberPrefix} = numberPrefixParser(folderName);
       const allItems = await Promise.all(

package/src/sidebars/index.ts

@@ -9,12 +9,16 @@ import fs from 'fs-extra';
 import importFresh from 'import-fresh';
 import type {SidebarsConfig, Sidebars, NormalizedSidebars} from './types';
 import type {NormalizeSidebarsParams} from '../types';
-import {validateSidebars} from './validation';
+import {validateSidebars, validateCategoryMetadataFile} from './validation';
 import {normalizeSidebars} from './normalization';
 import {processSidebars, type SidebarProcessorParams} from './processor';
 import path from 'path';
-import {createSlugger} from '@docusaurus/utils';
+import {createSlugger, Globby} from '@docusaurus/utils';
+import logger from '@docusaurus/logger';
 import type {PluginOptions} from '@docusaurus/plugin-content-docs';
+import Yaml from 'js-yaml';
+import {groupBy, mapValues} from 'lodash';
+import combinePromises from 'combine-promises';
 
 export const DefaultSidebars: SidebarsConfig = {
   defaultSidebar: [
@@ -38,6 +42,33 @@ export function resolveSidebarPathOption(
     : sidebarPathOption;
 }
 
+async function readCategoriesMetadata(contentPath: string) {
+  const categoryFiles = await Globby('**/_category_.{json,yml,yaml}', {
+    cwd: contentPath,
+  });
+  const categoryToFile = groupBy(categoryFiles, path.dirname);
+  return combinePromises(
+    mapValues(categoryToFile, async (files, folder) => {
+      const [filePath] = files;
+      if (files.length > 1) {
+        logger.warn`There are more than one category metadata files for path=${folder}: ${files.join(
+          ', ',
+        )}. The behavior is undetermined.`;
+      }
+      const content = await fs.readFile(
+        path.join(contentPath, filePath),
+        'utf-8',
+      );
+      try {
+        return validateCategoryMetadataFile(Yaml.load(content));
+      } catch (e) {
+        logger.error`The docs sidebar category metadata file path=${filePath} looks invalid!`;
+        throw e;
+      }
+    }),
+  );
+}
+
 async function loadSidebarsFileUnsafe(
   sidebarFilePath: string | false | undefined,
 ): Promise<SidebarsConfig> {
@@ -80,7 +111,7 @@ export async function loadNormalizedSidebars(
 // Note: sidebarFilePath must be absolute, use resolveSidebarPathOption
 export async function loadSidebars(
   sidebarFilePath: string | false | undefined,
-  options: SidebarProcessorParams,
+  options: Omit<SidebarProcessorParams, 'categoriesMetadata'>,
 ): Promise<Sidebars> {
   const normalizeSidebarsParams: NormalizeSidebarsParams = {
     ...options.sidebarOptions,
@@ -91,5 +122,8 @@ export async function loadSidebars(
     sidebarFilePath,
     normalizeSidebarsParams,
   );
-  return processSidebars(normalizedSidebars, options);
+  const categoriesMetadata = await readCategoriesMetadata(
+    options.version.contentPath,
+  );
+  return processSidebars(normalizedSidebars, {...options, categoriesMetadata});
 }

package/src/sidebars/processor.ts

@@ -19,6 +19,7 @@ import type {
   NormalizedSidebarItemCategory,
   SidebarItemCategory,
   SidebarItemAutogenerated,
+  CategoryMetadataFile,
 } from './types';
 import {transformSidebarItems} from './utils';
 import {DefaultSidebarItemsGenerator} from './generator';
@@ -39,6 +40,7 @@ export type SidebarProcessorParams = {
   version: VersionMetadata;
   categoryLabelSlugger: Slugger;
   sidebarOptions: SidebarOptions;
+  categoriesMetadata: Record<string, CategoryMetadataFile>;
 };
 
 function toSidebarItemsGeneratorDoc(
@@ -72,6 +74,7 @@ async function processSidebar(
     docs,
     version,
     sidebarOptions,
+    categoriesMetadata,
   } = params;
 
   // Just a minor lazy transformation optimization
@@ -101,6 +104,7 @@ async function processSidebar(
       isCategoryIndex,
       ...getSidebarItemsGeneratorDocsAndVersion(),
       options: sidebarOptions,
+      categoriesMetadata,
     });
     // TODO validate generated items: user can generate bad items
 

package/src/sidebars/types.ts

@@ -27,6 +27,12 @@ export type SidebarItemDoc = SidebarItemBase & {
   id: string;
 };
 
+export type SidebarItemHtml = SidebarItemBase & {
+  type: 'html';
+  value: string;
+  defaultStyle?: boolean;
+};
+
 export type SidebarItemLink = SidebarItemBase & {
   type: 'link';
   href: string;
@@ -87,6 +93,7 @@ export type SidebarCategoriesShorthand = {
 
 export type SidebarItemConfig =
   | SidebarItemDoc
+  | SidebarItemHtml
   | SidebarItemLink
   | SidebarItemAutogenerated
   | SidebarItemCategoryConfig
@@ -108,6 +115,7 @@ export type NormalizedSidebarItemCategory = Expand<
 
 export type NormalizedSidebarItem =
   | SidebarItemDoc
+  | SidebarItemHtml
   | SidebarItemLink
   | NormalizedSidebarItemCategory
   | SidebarItemAutogenerated;
@@ -131,6 +139,7 @@ export type SidebarItemCategoryWithGeneratedIndex =
 
 export type SidebarItem =
   | SidebarItemDoc
+  | SidebarItemHtml
   | SidebarItemLink
   | SidebarItemCategory;
 
@@ -158,7 +167,12 @@ export type PropSidebarItemLink = SidebarItemLink & {
   docId?: string;
 };
 
-export type PropSidebarItem = PropSidebarItemLink | PropSidebarItemCategory;
+export type PropSidebarItemHtml = SidebarItemHtml;
+
+export type PropSidebarItem =
+  | PropSidebarItemLink
+  | PropSidebarItemCategory
+  | PropSidebarItemHtml;
 export type PropSidebar = PropSidebarItem[];
 export type PropSidebars = {
   [sidebarId: string]: PropSidebar;
@@ -174,6 +188,20 @@ export type PropVersionDocs = {
   [docId: string]: PropVersionDoc;
 };
 
+export type CategoryMetadataFile = {
+  label?: string;
+  position?: number;
+  collapsed?: boolean;
+  collapsible?: boolean;
+  className?: string;
+  link?: SidebarItemCategoryLinkConfig | null;
+
+  // TODO should we allow "items" here? how would this work? would an
+  // "autogenerated" type be allowed?
+  // This mkdocs plugin do something like that: https://github.com/lukasgeiter/mkdocs-awesome-pages-plugin/
+  // cf comment: https://github.com/facebook/docusaurus/issues/3464#issuecomment-784765199
+};
+
 // Reduce API surface for options.sidebarItemsGenerator
 // The user-provided generator fn should receive only a subset of metadata
 // A change to any of these metadata can be considered as a breaking change
@@ -197,6 +225,7 @@ export type SidebarItemsGeneratorArgs = {
   docs: SidebarItemsGeneratorDoc[];
   numberPrefixParser: NumberPrefixParser;
   isCategoryIndex: CategoryIndexMatcher;
+  categoriesMetadata: Record<string, CategoryMetadataFile>;
   options: SidebarOptions;
 };
 export type SidebarItemsGenerator = (

package/src/sidebars/validation.ts

@@ -12,15 +12,16 @@ import type {
   SidebarItemBase,
   SidebarItemAutogenerated,
   SidebarItemDoc,
+  SidebarItemHtml,
   SidebarItemLink,
   SidebarItemCategoryConfig,
   SidebarItemCategoryLink,
   SidebarsConfig,
   SidebarItemCategoryLinkDoc,
   SidebarItemCategoryLinkGeneratedIndex,
+  CategoryMetadataFile,
 } from './types';
 import {isCategoriesShorthand} from './utils';
-import type {CategoryMetadataFile} from './generator';
 
 // 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
@@ -48,6 +49,12 @@ const sidebarItemDocSchema = sidebarItemBaseSchema.append<SidebarItemDoc>({
   label: Joi.string(),
 });
 
+const sidebarItemHtmlSchema = sidebarItemBaseSchema.append<SidebarItemHtml>({
+  type: 'html',
+  value: Joi.string().required(),
+  defaultStyle: Joi.boolean().default(false),
+});
+
 const sidebarItemLinkSchema = sidebarItemBaseSchema.append<SidebarItemLink>({
   type: 'link',
   href: URISchema.required(),
@@ -117,6 +124,7 @@ const sidebarItemSchema: Joi.Schema<SidebarItemConfig> = Joi.object()
         is: Joi.string().valid('doc', 'ref').required(),
         then: sidebarItemDocSchema,
       },
+      {is: 'html', then: sidebarItemHtmlSchema},
       {is: 'autogenerated', then: sidebarItemAutogeneratedSchema},
       {is: 'category', then: sidebarItemCategorySchema},
       {