@docusaurus/plugin-content-docs 2.0.0-beta.21 → 2.0.0-beta.22

package/package.json

@@ -1,14 +1,23 @@
 {
   "name": "@docusaurus/plugin-content-docs",
-  "version": "2.0.0-beta.21",
+  "version": "2.0.0-beta.22",
   "description": "Docs plugin for Docusaurus.",
   "main": "lib/index.js",
   "sideEffects": false,
   "exports": {
     "./src/*": "./src/*",
-    "./client": "./lib/client/index.js",
-    "./server": "./lib/server-export.js",
-    ".": "./lib/index.js"
+    "./client": {
+      "type": "./lib/client/index.d.ts",
+      "default": "./lib/client/index.js"
+    },
+    "./server": {
+      "type": "./lib/server-export.d.ts",
+      "default": "./lib/server-export.js"
+    },
+    ".": {
+      "types": "./src/plugin-content-docs.d.ts",
+      "default": "./lib/index.js"
+    }
   },
   "types": "src/plugin-content-docs.d.ts",
   "scripts": {
@@ -25,31 +34,31 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/core": "2.0.0-beta.21",
-    "@docusaurus/logger": "2.0.0-beta.21",
-    "@docusaurus/mdx-loader": "2.0.0-beta.21",
-    "@docusaurus/utils": "2.0.0-beta.21",
-    "@docusaurus/utils-validation": "2.0.0-beta.21",
+    "@docusaurus/core": "2.0.0-beta.22",
+    "@docusaurus/logger": "2.0.0-beta.22",
+    "@docusaurus/mdx-loader": "2.0.0-beta.22",
+    "@docusaurus/module-type-aliases": "2.0.0-beta.22",
+    "@docusaurus/types": "2.0.0-beta.22",
+    "@docusaurus/utils": "2.0.0-beta.22",
+    "@docusaurus/utils-validation": "2.0.0-beta.22",
+    "@types/react-router-config": "^5.0.6",
     "combine-promises": "^1.1.0",
     "fs-extra": "^10.1.0",
     "import-fresh": "^3.3.0",
     "js-yaml": "^4.1.0",
     "lodash": "^4.17.21",
-    "remark-admonitions": "^1.2.1",
     "tslib": "^2.4.0",
     "utility-types": "^3.10.0",
-    "webpack": "^5.72.1"
+    "webpack": "^5.73.0"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "2.0.0-beta.21",
     "@docusaurus/types": "2.0.0-beta.21",
     "@types/js-yaml": "^4.0.5",
     "@types/picomatch": "^2.3.0",
     "commander": "^5.1.0",
     "escape-string-regexp": "^4.0.0",
     "picomatch": "^2.3.1",
-    "shelljs": "^0.8.5",
-    "utility-types": "^3.10.0"
+    "shelljs": "^0.8.5"
   },
   "peerDependencies": {
     "react": "^16.8.4 || ^17.0.0",
@@ -58,5 +67,5 @@
   "engines": {
     "node": ">=16.14"
   },
-  "gitHead": "69ac49fc6909517f13615ee40290c4bd00c39df4"
+  "gitHead": "daf9e462c4eebb7ac26a940932311f987e768f87"
 }

package/src/cli.ts

@@ -85,13 +85,17 @@ export async function cliDocsVersionCommand(
 
   await Promise.all(
     i18n.locales.map(async (locale) => {
+      const localizationDir = path.resolve(
+        siteDir,
+        i18n.path,
+        i18n.localeConfigs[locale]!.path,
+      );
       // Copy docs files.
       const docsDir =
         locale === i18n.defaultLocale
           ? path.resolve(siteDir, docsPath)
           : getDocsDirPathLocalized({
-              siteDir,
-              locale,
+              localizationDir,
               pluginId,
               versionName: CURRENT_VERSION_NAME,
             });
@@ -114,8 +118,7 @@ export async function cliDocsVersionCommand(
         locale === i18n.defaultLocale
           ? getVersionDocsDirPath(siteDir, pluginId, version)
           : getDocsDirPathLocalized({
-              siteDir,
-              locale,
+              localizationDir,
               pluginId,
               versionName: version,
             });

package/src/client/index.ts

@@ -18,15 +18,60 @@ import {
   getActiveDocContext,
   getDocVersionSuggestions,
 } from './docsClientUtils';
-import type {
-  GlobalPluginData,
-  GlobalVersion,
-  ActivePlugin,
-  ActiveDocContext,
-  DocVersionSuggestions,
-} from '@docusaurus/plugin-content-docs/client';
 import type {UseDataOptions} from '@docusaurus/types';
 
+export type ActivePlugin = {
+  pluginId: string;
+  pluginData: GlobalPluginData;
+};
+export type ActiveDocContext = {
+  activeVersion?: GlobalVersion;
+  activeDoc?: GlobalDoc;
+  alternateDocVersions: {[versionName: string]: GlobalDoc};
+};
+export type GlobalDoc = {
+  /**
+   * For generated index pages, this is the `slug`, **not** `permalink`
+   * (without base URL). Because slugs have leading slashes but IDs don't,
+   * there won't be clashes.
+   */
+  id: string;
+  path: string;
+  sidebar: string | undefined;
+};
+
+export type GlobalVersion = {
+  name: string;
+  label: string;
+  isLast: boolean;
+  path: string;
+  /** The doc with `slug: /`, or first doc in first sidebar */
+  mainDocId: string;
+  docs: GlobalDoc[];
+  /** Unversioned IDs. In development, this list is empty. */
+  draftIds: string[];
+  sidebars?: {[sidebarId: string]: GlobalSidebar};
+};
+
+export type GlobalSidebar = {
+  link?: {
+    label: string;
+    path: string;
+  };
+  // ... we may add other things here later
+};
+export type GlobalPluginData = {
+  path: string;
+  versions: GlobalVersion[];
+  breadcrumbs: boolean;
+};
+export type DocVersionSuggestions = {
+  /** Suggest the latest version */
+  latestVersionSuggestion: GlobalVersion;
+  /** Suggest the same doc, in latest version (if one exists) */
+  latestDocSuggestion?: GlobalDoc;
+};
+
 // Important to use a constant object to avoid React useEffect executions etc.
 // see https://github.com/facebook/docusaurus/issues/5089
 const StableEmptyObject = {};
@@ -71,6 +116,7 @@ export function useActivePluginAndVersion(
   };
 }
 
+/** Versions are returned ordered (most recent first). */
 export function useVersions(pluginId: string | undefined): GlobalVersion[] {
   const data = useDocsData(pluginId);
   return data.versions;
@@ -81,6 +127,10 @@ export function useLatestVersion(pluginId: string | undefined): GlobalVersion {
   return getLatestVersion(data);
 }
 
+/**
+ * Returns `undefined` on doc-unrelated pages, because there's no version
+ * currently considered as active.
+ */
 export function useActiveVersion(
   pluginId: string | undefined,
 ): GlobalVersion | undefined {
@@ -96,7 +146,9 @@ export function useActiveDocContext(
   const {pathname} = useLocation();
   return getActiveDocContext(data, pathname);
 }
-
+/**
+ * Useful to say "hey, you are not on the latest docs version, please switch"
+ */
 export function useDocVersionSuggestions(
   pluginId: string | undefined,
 ): DocVersionSuggestions {

package/src/docs.ts

@@ -37,6 +37,7 @@ import type {
   VersionMetadata,
   DocFrontMatter,
   LoadedVersion,
+  FileChange,
 } from '@docusaurus/plugin-content-docs';
 import type {LoadContext} from '@docusaurus/types';
 import type {SidebarsUtils} from './sidebars/utils';
@@ -50,9 +51,21 @@ type LastUpdateOptions = Pick<
 async function readLastUpdateData(
   filePath: string,
   options: LastUpdateOptions,
+  lastUpdateFrontMatter: FileChange | undefined,
 ): Promise<LastUpdateData> {
   const {showLastUpdateAuthor, showLastUpdateTime} = options;
   if (showLastUpdateAuthor || showLastUpdateTime) {
+    const frontMatterTimestamp = lastUpdateFrontMatter?.date
+      ? new Date(lastUpdateFrontMatter.date).getTime() / 1000
+      : undefined;
+
+    if (lastUpdateFrontMatter?.author && lastUpdateFrontMatter.date) {
+      return {
+        lastUpdatedAt: frontMatterTimestamp,
+        lastUpdatedBy: lastUpdateFrontMatter.author,
+      };
+    }
+
     // Use fake data in dev for faster development.
     const fileLastUpdateData =
       process.env.NODE_ENV === 'production'
@@ -61,14 +74,16 @@ async function readLastUpdateData(
             author: 'Author',
             timestamp: 1539502055,
           };
-
-    if (fileLastUpdateData) {
-      const {author, timestamp} = fileLastUpdateData;
-      return {
-        lastUpdatedAt: showLastUpdateTime ? timestamp : undefined,
-        lastUpdatedBy: showLastUpdateAuthor ? author : undefined,
-      };
-    }
+    const {author, timestamp} = fileLastUpdateData ?? {};
+
+    return {
+      lastUpdatedBy: showLastUpdateAuthor
+        ? lastUpdateFrontMatter?.author ?? author
+        : undefined,
+      lastUpdatedAt: showLastUpdateTime
+        ? frontMatterTimestamp ?? timestamp
+        : undefined,
+    };
   }
 
   return {};
@@ -80,7 +95,6 @@ export async function readDocFile(
     'contentPath' | 'contentPathLocalized'
   >,
   source: string,
-  options: LastUpdateOptions,
 ): Promise<DocFile> {
   const contentPath = await getFolderContainingFile(
     getContentPathList(versionMetadata),
@@ -89,11 +103,8 @@ export async function readDocFile(
 
   const filePath = path.join(contentPath, source);
 
-  const [content, lastUpdate] = await Promise.all([
-    fs.readFile(filePath, 'utf-8'),
-    readLastUpdateData(filePath, options),
-  ]);
-  return {source, content, lastUpdate, contentPath, filePath};
+  const content = await fs.readFile(filePath, 'utf-8');
+  return {source, content, contentPath, filePath};
 }
 
 export async function readVersionDocs(
@@ -108,7 +119,7 @@ export async function readVersionDocs(
     ignore: options.exclude,
   });
   return Promise.all(
-    sources.map((source) => readDocFile(versionMetadata, source, options)),
+    sources.map((source) => readDocFile(versionMetadata, source)),
   );
 }
 
@@ -125,7 +136,7 @@ function isDraftForEnvironment({
   return (env === 'production' && frontMatter.draft) ?? false;
 }
 
-function doProcessDocMetadata({
+async function doProcessDocMetadata({
   docFile,
   versionMetadata,
   context,
@@ -137,8 +148,8 @@ function doProcessDocMetadata({
   context: LoadContext;
   options: MetadataOptions;
   env: DocEnv;
-}): DocMetadataBase {
-  const {source, content, lastUpdate, contentPath, filePath} = docFile;
+}): Promise<DocMetadataBase> {
+  const {source, content, contentPath, filePath} = docFile;
   const {siteDir, i18n} = context;
 
   const {
@@ -155,8 +166,15 @@ function doProcessDocMetadata({
     // (01-MyFolder/01-MyDoc.md => MyFolder/MyDoc)
     // but allow to disable this behavior with front matter
     parse_number_prefixes: parseNumberPrefixes = true,
+    last_update: lastUpdateFrontMatter,
   } = frontMatter;
 
+  const lastUpdate = await readLastUpdateData(
+    filePath,
+    options,
+    lastUpdateFrontMatter,
+  );
+
   // E.g. api/plugins/myDoc -> myDoc; myDoc -> myDoc
   const sourceFileNameWithoutExtension = path.basename(
     source,
@@ -252,6 +270,21 @@ function doProcessDocMetadata({
 
   const draft = isDraftForEnvironment({env, frontMatter});
 
+  const formatDate = (locale: string, date: Date, calendar: string): string => {
+    try {
+      return new Intl.DateTimeFormat(locale, {
+        day: 'numeric',
+        month: 'short',
+        year: 'numeric',
+        timeZone: 'UTC',
+        calendar,
+      }).format(date);
+    } catch (err) {
+      logger.error`Can't format docs lastUpdatedAt date "${String(date)}"`;
+      throw err;
+    }
+  };
+
   // Assign all of object properties during instantiation (if possible) for
   // NodeJS optimization.
   // Adding properties to object after instantiation will cause hidden
@@ -272,9 +305,11 @@ function doProcessDocMetadata({
     lastUpdatedBy: lastUpdate.lastUpdatedBy,
     lastUpdatedAt: lastUpdate.lastUpdatedAt,
     formattedLastUpdatedAt: lastUpdate.lastUpdatedAt
-      ? new Intl.DateTimeFormat(i18n.currentLocale, {
-          calendar: i18n.localeConfigs[i18n.currentLocale]!.calendar,
-        }).format(lastUpdate.lastUpdatedAt * 1000)
+      ? formatDate(
+          i18n.currentLocale,
+          new Date(lastUpdate.lastUpdatedAt * 1000),
+          i18n.localeConfigs[i18n.currentLocale]!.calendar,
+        )
       : undefined,
     sidebarPosition,
     frontMatter,
@@ -287,7 +322,7 @@ export function processDocMetadata(args: {
   context: LoadContext;
   options: MetadataOptions;
   env: DocEnv;
-}): DocMetadataBase {
+}): Promise<DocMetadataBase> {
   try {
     return doProcessDocMetadata(args);
   } catch (err) {

package/src/frontMatter.ts

@@ -14,6 +14,9 @@ import {
 } from '@docusaurus/utils-validation';
 import type {DocFrontMatter} from '@docusaurus/plugin-content-docs';
 
+const FrontMatterLastUpdateErrorMessage =
+  '{{#label}} does not look like a valid front matter FileChange object. Please use a FileChange object (with an author and/or date).';
+
 // NOTE: we don't add any default value on purpose here
 // We don't want default values to magically appear in doc metadata and props
 // While the user did not provide those values explicitly
@@ -42,6 +45,15 @@ const DocFrontMatterSchema = Joi.object<DocFrontMatter>({
   pagination_prev: Joi.string().allow(null),
   draft: Joi.boolean(),
   ...FrontMatterTOCHeadingLevels,
+  last_update: Joi.object({
+    author: Joi.string(),
+    date: Joi.date().raw(),
+  })
+    .or('author', 'date')
+    .messages({
+      'object.missing': FrontMatterLastUpdateErrorMessage,
+      'object.base': FrontMatterLastUpdateErrorMessage,
+    }),
 }).unknown();
 
 export function validateDocFrontMatter(frontMatter: {

package/src/index.ts

@@ -13,7 +13,6 @@ import {
   docuHash,
   aliasedSitePath,
   getContentPathList,
-  reportMessage,
   posixPath,
   addTrailingPathSeparator,
   createAbsoluteFilePathMatcher,
@@ -100,9 +99,9 @@ export default async function pluginContentDocs(
         .command(command)
         .arguments('<version>')
         .description(commandDescription)
-        .action((version: unknown) => {
-          cliDocsVersionCommand(version, options, context);
-        });
+        .action((version: unknown) =>
+          cliDocsVersionCommand(version, options, context),
+        );
     },
 
     getTranslationFiles({content}) {
@@ -330,13 +329,9 @@ export default async function pluginContentDocs(
         sourceToPermalink: getSourceToPermalink(),
         versionsMetadata,
         onBrokenMarkdownLink: (brokenMarkdownLink) => {
-          if (siteConfig.onBrokenMarkdownLinks === 'ignore') {
-            return;
-          }
-          reportMessage(
-            `Docs markdown link couldn't be resolved: (${brokenMarkdownLink.link}) in ${brokenMarkdownLink.filePath} for version ${brokenMarkdownLink.contentPaths.versionName}`,
+          logger.report(
             siteConfig.onBrokenMarkdownLinks,
-          );
+          )`Docs markdown link couldn't be resolved: (url=${brokenMarkdownLink.link}) in path=${brokenMarkdownLink.filePath} for version number=${brokenMarkdownLink.contentPaths.versionName}`;
         },
       };
 
@@ -352,6 +347,7 @@ export default async function pluginContentDocs(
             {
               loader: require.resolve('@docusaurus/mdx-loader'),
               options: {
+                admonitions: options.admonitions,
                 remarkPlugins,
                 rehypePlugins,
                 beforeDefaultRehypePlugins,

package/src/lastUpdate.ts

@@ -16,7 +16,7 @@ let showedGitRequirementError = false;
 let showedFileNotTrackedError = false;
 
 export async function getFileLastUpdate(
-  filePath?: string,
+  filePath: string,
 ): Promise<{timestamp: number; author: string} | null> {
   if (!filePath) {
     return null;

package/src/options.ts

@@ -14,7 +14,6 @@ import {
   URISchema,
 } from '@docusaurus/utils-validation';
 import {GlobExcludeDefault} from '@docusaurus/utils';
-import admonitions from 'remark-admonitions';
 import {DefaultSidebarItemsGenerator} from './sidebars/generator';
 import {
   DefaultNumberPrefixParser,
@@ -42,7 +41,7 @@ export const DEFAULT_OPTIONS: Omit<PluginOptions, 'id' | 'sidebarPath'> = {
   beforeDefaultRehypePlugins: [],
   showLastUpdateTime: false,
   showLastUpdateAuthor: false,
-  admonitions: {},
+  admonitions: true,
   includeCurrentVersion: true,
   disableVersioning: false,
   lastVersion: undefined,
@@ -123,9 +122,7 @@ const OptionsSchema = Joi.object<PluginOptions>({
   beforeDefaultRehypePlugins: RehypePluginsSchema.default(
     DEFAULT_OPTIONS.beforeDefaultRehypePlugins,
   ),
-  admonitions: Joi.alternatives()
-    .try(AdmonitionsSchema, Joi.boolean().invalid(true))
-    .default(DEFAULT_OPTIONS.admonitions),
+  admonitions: AdmonitionsSchema.default(DEFAULT_OPTIONS.admonitions),
   showLastUpdateTime: Joi.bool().default(DEFAULT_OPTIONS.showLastUpdateTime),
   showLastUpdateAuthor: Joi.bool().default(
     DEFAULT_OPTIONS.showLastUpdateAuthor,
@@ -167,11 +164,5 @@ export function validateOptions({
 
   const normalizedOptions = validate(OptionsSchema, options);
 
-  if (normalizedOptions.admonitions) {
-    normalizedOptions.remarkPlugins = normalizedOptions.remarkPlugins.concat([
-      [admonitions, normalizedOptions.admonitions],
-    ]);
-  }
-
   return normalizedOptions;
 }

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

@@ -8,7 +8,8 @@
 /// <reference types="@docusaurus/module-type-aliases" />
 
 declare module '@docusaurus/plugin-content-docs' {
-  import type {MDXOptions} from '@docusaurus/mdx-loader';
+  import type {MDXOptions, LoadedMDXContent} from '@docusaurus/mdx-loader';
+
   import type {
     ContentPaths,
     FrontMatterTag,
@@ -23,6 +24,14 @@ declare module '@docusaurus/plugin-content-docs' {
     image?: string;
   };
 
+  export type FileChange = {
+    author?: string;
+    /** Date can be any
+     * [parsable date string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/parse).
+     */
+    date?: Date | string;
+  };
+
   /**
    * Custom callback for parsing number prefixes from file/folder names.
    */
@@ -198,7 +207,6 @@ declare module '@docusaurus/plugin-content-docs' {
       docTagsListComponent: string;
       /** Root component of the generated category index page. */
       docCategoryGeneratedIndexComponent: string;
-      admonitions: {[key: string]: unknown};
       sidebarItemsGenerator: import('./sidebars/types').SidebarItemsGeneratorOption;
       /**
        * URL route for the tags section of your doc version. Will be appended to
@@ -371,6 +379,8 @@ declare module '@docusaurus/plugin-content-docs' {
     pagination_prev?: string | null;
     /** Should this doc be excluded from production builds? */
     draft?: boolean;
+    /** Allows overriding the last updated author and/or date. */
+    last_update?: FileChange;
   };
 
   export type LastUpdateData = {
@@ -482,6 +492,12 @@ declare module '@docusaurus/plugin-content-docs' {
     [docId: string]: PropVersionDoc;
   };
 
+  export type PropDocContent = LoadedMDXContent<
+    DocFrontMatter,
+    DocMetadata,
+    Assets
+  >;
+
   export type PropVersionMetadata = Pick<
     VersionMetadata,
     'label' | 'banner' | 'badge' | 'className' | 'isLast'
@@ -540,13 +556,7 @@ declare module '@docusaurus/plugin-content-docs' {
 }
 
 declare module '@theme/DocItem' {
-  import type {LoadedMDXContent} from '@docusaurus/mdx-loader';
-  import type {
-    PropVersionMetadata,
-    Assets,
-    DocMetadata,
-    DocFrontMatter,
-  } from '@docusaurus/plugin-content-docs';
+  import type {PropDocContent} from '@docusaurus/plugin-content-docs';
 
   export type DocumentRoute = {
     readonly component: () => JSX.Element;
@@ -557,8 +567,7 @@ declare module '@theme/DocItem' {
 
   export interface Props {
     readonly route: DocumentRoute;
-    readonly versionMetadata: PropVersionMetadata;
-    readonly content: LoadedMDXContent<DocFrontMatter, DocMetadata, Assets>;
+    readonly content: PropDocContent;
   }
 
   export default function DocItem(props: Props): JSX.Element;
@@ -607,89 +616,3 @@ declare module '@theme/DocPage' {
 
   export default function DocPage(props: Props): JSX.Element;
 }
-
-// TODO TS only supports reading `exports` in 4.7. We will need to merge the
-// type defs (and JSDoc) here with the implementation after that
-declare module '@docusaurus/plugin-content-docs/client' {
-  import type {UseDataOptions} from '@docusaurus/types';
-
-  export type ActivePlugin = {
-    pluginId: string;
-    pluginData: GlobalPluginData;
-  };
-  export type ActiveDocContext = {
-    activeVersion?: GlobalVersion;
-    activeDoc?: GlobalDoc;
-    alternateDocVersions: {[versionName: string]: GlobalDoc};
-  };
-  export type GlobalDoc = {
-    /**
-     * For generated index pages, this is the `slug`, **not** `permalink`
-     * (without base URL). Because slugs have leading slashes but IDs don't,
-     * there won't be clashes.
-     */
-    id: string;
-    path: string;
-    sidebar: string | undefined;
-  };
-
-  export type GlobalVersion = {
-    name: string;
-    label: string;
-    isLast: boolean;
-    path: string;
-    /** The doc with `slug: /`, or first doc in first sidebar */
-    mainDocId: string;
-    docs: GlobalDoc[];
-    /** Unversioned IDs. In development, this list is empty. */
-    draftIds: string[];
-    sidebars?: {[sidebarId: string]: GlobalSidebar};
-  };
-
-  export type GlobalSidebar = {
-    link?: {
-      label: string;
-      path: string;
-    };
-    // ... we may add other things here later
-  };
-  export type GlobalPluginData = {
-    path: string;
-    versions: GlobalVersion[];
-    breadcrumbs: boolean;
-  };
-  export type DocVersionSuggestions = {
-    /** Suggest the latest version */
-    latestVersionSuggestion: GlobalVersion;
-    /** Suggest the same doc, in latest version (if one exists) */
-    latestDocSuggestion?: GlobalDoc;
-  };
-
-  export const useAllDocsData: () => {[pluginId: string]: GlobalPluginData};
-  export const useDocsData: (pluginId?: string) => GlobalPluginData;
-  export const useActivePlugin: (
-    options?: UseDataOptions,
-  ) => ActivePlugin | undefined;
-  export const useActivePluginAndVersion: (
-    options?: UseDataOptions,
-  ) =>
-    | {activePlugin: ActivePlugin; activeVersion: GlobalVersion | undefined}
-    | undefined;
-  /** Versions are returned ordered (most recent first). */
-  export const useVersions: (pluginId?: string) => GlobalVersion[];
-  export const useLatestVersion: (pluginId?: string) => GlobalVersion;
-  /**
-   * Returns `undefined` on doc-unrelated pages, because there's no version
-   * currently considered as active.
-   */
-  export const useActiveVersion: (
-    pluginId?: string,
-  ) => GlobalVersion | undefined;
-  export const useActiveDocContext: (pluginId?: string) => ActiveDocContext;
-  /**
-   * Useful to say "hey, you are not on the latest docs version, please switch"
-   */
-  export const useDocVersionSuggestions: (
-    pluginId?: string,
-  ) => DocVersionSuggestions;
-}

package/src/props.ts

@@ -73,10 +73,28 @@ Available document ids are:
     }
   }
 
+  function getCategoryLinkCustomProps(
+    link: SidebarItemCategoryLink | undefined,
+  ) {
+    switch (link?.type) {
+      case 'doc':
+        return getDocById(link.id).frontMatter.sidebar_custom_props;
+      default:
+        return undefined;
+    }
+  }
+
   function convertCategory(item: SidebarItemCategory): PropSidebarItemCategory {
     const {link, ...rest} = item;
     const href = getCategoryLinkHref(link);
-    return {...rest, items: item.items.map(normalizeItem), ...(href && {href})};
+    const customProps = item.customProps ?? getCategoryLinkCustomProps(link);
+
+    return {
+      ...rest,
+      items: item.items.map(normalizeItem),
+      ...(href && {href}),
+      ...(customProps && {customProps}),
+    };
   }
 
   function normalizeItem(item: SidebarItem): PropSidebarItem {