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

package/lib/tags.js

@@ -8,8 +8,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getVersionTags = void 0;
 const tslib_1 = require("tslib");
-const utils_1 = require("@docusaurus/utils");
 const lodash_1 = tslib_1.__importDefault(require("lodash"));
+const utils_1 = require("@docusaurus/utils");
 function getVersionTags(docs) {
     const groups = (0, utils_1.groupTaggedItems)(docs, (doc) => doc.tags);
     return lodash_1.default.mapValues(groups, (group) => ({

package/lib/translations.js

@@ -9,9 +9,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.translateLoadedContent = exports.getLoadedContentTranslationFiles = void 0;
 const tslib_1 = require("tslib");
 const lodash_1 = tslib_1.__importDefault(require("lodash"));
-const utils_1 = require("./sidebars/utils");
-const utils_2 = require("@docusaurus/utils");
+const utils_1 = require("@docusaurus/utils");
 const constants_1 = require("./constants");
+const utils_2 = require("./sidebars/utils");
 function getVersionFileName(versionName) {
     if (versionName === constants_1.CURRENT_VERSION_NAME) {
         return versionName;
@@ -31,7 +31,7 @@ function getNormalizedSidebarName({ versionName, sidebarName, }) {
     return rest.join('/');
 }
 function getSidebarTranslationFileContent(sidebar, sidebarName) {
-    const categories = (0, utils_1.collectSidebarCategories)(sidebar);
+    const categories = (0, utils_2.collectSidebarCategories)(sidebar);
     const categoryContent = Object.fromEntries(categories.flatMap((category) => {
         const entries = [];
         entries.push([
@@ -63,7 +63,7 @@ function getSidebarTranslationFileContent(sidebar, sidebarName) {
         }
         return entries;
     }));
-    const links = (0, utils_1.collectSidebarLinks)(sidebar);
+    const links = (0, utils_2.collectSidebarLinks)(sidebar);
     const linksContent = Object.fromEntries(links.map((link) => [
         `sidebar.${sidebarName}.link.${link.label}`,
         {
@@ -71,7 +71,7 @@ function getSidebarTranslationFileContent(sidebar, sidebarName) {
             description: `The label for link ${link.label} in sidebar ${sidebarName}, linking to ${link.href}`,
         },
     ]));
-    return (0, utils_2.mergeTranslations)([categoryContent, linksContent]);
+    return (0, utils_1.mergeTranslations)([categoryContent, linksContent]);
 }
 function translateSidebar({ sidebar, sidebarName, sidebarsTranslations, }) {
     function transformSidebarCategoryLink(category) {
@@ -89,7 +89,7 @@ function translateSidebar({ sidebar, sidebarName, sidebarsTranslations, }) {
         }
         return category.link;
     }
-    return (0, utils_1.transformSidebarItems)(sidebar, (item) => {
+    return (0, utils_2.transformSidebarItems)(sidebar, (item) => {
         if (item.type === 'category') {
             const link = transformSidebarCategoryLink(item);
             return {
@@ -110,7 +110,7 @@ function translateSidebar({ sidebar, sidebarName, sidebarsTranslations, }) {
     });
 }
 function getSidebarsTranslations(version) {
-    return (0, utils_2.mergeTranslations)(Object.entries(version.sidebars).map(([sidebarName, sidebar]) => {
+    return (0, utils_1.mergeTranslations)(Object.entries(version.sidebars).map(([sidebarName, sidebar]) => {
         const normalizedSidebarName = getNormalizedSidebarName({
             sidebarName,
             versionName: version.versionName,
@@ -139,7 +139,7 @@ function getVersionTranslationFiles(version) {
     return [
         {
             path: getVersionFileName(version.versionName),
-            content: (0, utils_2.mergeTranslations)([versionTranslations, sidebarsTranslations]),
+            content: (0, utils_1.mergeTranslations)([versionTranslations, sidebarsTranslations]),
         },
     ];
 }

package/lib/versions/files.d.ts

@@ -18,6 +18,13 @@ export declare function getDocsDirPathLocalized({ siteDir, locale, pluginId, ver
 }): string;
 /** `community` => `[siteDir]/community_versions.json` */
 export declare function getVersionsFilePath(siteDir: string, pluginId: string): string;
+/**
+ * Reads the plugin's respective `versions.json` file, and returns its content.
+ *
+ * @throws Throws if validation fails, i.e. `versions.json` doesn't contain an
+ * array of valid version names.
+ */
+export declare function readVersionsFile(siteDir: string, pluginId: string): Promise<string[] | null>;
 /**
  * Reads the `versions.json` file, and returns an ordered list of version names.
  *

package/lib/versions/files.js

@@ -6,13 +6,13 @@
  * LICENSE file in the root directory of this source tree.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getVersionMetadataPaths = exports.readVersionNames = exports.getVersionsFilePath = exports.getDocsDirPathLocalized = exports.getVersionSidebarsPath = exports.getVersionDocsDirPath = void 0;
+exports.getVersionMetadataPaths = exports.readVersionNames = exports.readVersionsFile = exports.getVersionsFilePath = exports.getDocsDirPathLocalized = exports.getVersionSidebarsPath = exports.getVersionDocsDirPath = 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"));
+const utils_1 = require("@docusaurus/utils");
 const constants_1 = require("../constants");
 const validation_1 = require("./validation");
-const utils_1 = require("@docusaurus/utils");
 /** Add a prefix like `community_version-1.0.0`. No-op for default instance. */
 function addPluginIdPrefix(fileOrDir, pluginId) {
     return pluginId === utils_1.DEFAULT_PLUGIN_ID
@@ -63,6 +63,7 @@ async function readVersionsFile(siteDir, pluginId) {
     }
     return null;
 }
+exports.readVersionsFile = readVersionsFile;
 /**
  * Reads the `versions.json` file, and returns an ordered list of version names.
  *

package/lib/versions/index.js

@@ -9,8 +9,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.readVersionsMetadata = exports.filterVersions = exports.getVersionBadge = exports.getVersionBanner = exports.getDefaultVersionBanner = void 0;
 const tslib_1 = require("tslib");
 const path_1 = tslib_1.__importDefault(require("path"));
-const constants_1 = require("../constants");
 const utils_1 = require("@docusaurus/utils");
+const constants_1 = require("../constants");
 const validation_1 = require("./validation");
 const files_1 = require("./files");
 function getVersionEditUrls({ contentPath, contentPathLocalized, context, options, }) {

package/lib/versions/validation.js

@@ -11,7 +11,7 @@ const tslib_1 = require("tslib");
 const lodash_1 = tslib_1.__importDefault(require("lodash"));
 function validateVersionName(name) {
     if (typeof name !== 'string') {
-        throw new Error(`Versions should be strings. Found type "${typeof name}" for version "${name}".`);
+        throw new Error(`Versions should be strings. Found type "${typeof name}" for version ${JSON.stringify(name)}.`);
     }
     if (!name.trim()) {
         throw new Error(`Invalid version name "${name}": version name must contain at least one non-whitespace character.`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/plugin-content-docs",
-  "version": "2.0.0-beta.20",
+  "version": "2.0.0-beta.21",
   "description": "Docs plugin for Docusaurus.",
   "main": "lib/index.js",
   "sideEffects": false,
@@ -12,8 +12,8 @@
   },
   "types": "src/plugin-content-docs.d.ts",
   "scripts": {
-    "build": "tsc",
-    "watch": "tsc --watch"
+    "build": "tsc --build",
+    "watch": "tsc --build --watch"
   },
   "publishConfig": {
     "access": "public"
@@ -25,11 +25,11 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/core": "2.0.0-beta.20",
-    "@docusaurus/logger": "2.0.0-beta.20",
-    "@docusaurus/mdx-loader": "2.0.0-beta.20",
-    "@docusaurus/utils": "2.0.0-beta.20",
-    "@docusaurus/utils-validation": "2.0.0-beta.20",
+    "@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",
     "combine-promises": "^1.1.0",
     "fs-extra": "^10.1.0",
     "import-fresh": "^3.3.0",
@@ -38,11 +38,11 @@
     "remark-admonitions": "^1.2.1",
     "tslib": "^2.4.0",
     "utility-types": "^3.10.0",
-    "webpack": "^5.72.0"
+    "webpack": "^5.72.1"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "2.0.0-beta.20",
-    "@docusaurus/types": "2.0.0-beta.20",
+    "@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",
@@ -56,7 +56,7 @@
     "react-dom": "^16.8.4 || ^17.0.0"
   },
   "engines": {
-    "node": ">=14"
+    "node": ">=16.14"
   },
-  "gitHead": "ed5cdba401a5948e187e927039b142a0decc702d"
+  "gitHead": "69ac49fc6909517f13615ee40290c4bd00c39df4"
 }

package/src/categoryGeneratedIndex.ts

@@ -5,13 +5,13 @@
  * LICENSE file in the root directory of this source tree.
  */
 
+import {type SidebarsUtils, toNavigationLink} from './sidebars/utils';
+import {createDocsByIdIndex} from './docs';
 import type {
   CategoryGeneratedIndexMetadata,
   DocMetadataBase,
 } from '@docusaurus/plugin-content-docs';
 import type {SidebarItemCategoryWithGeneratedIndex} from './sidebars/types';
-import {type SidebarsUtils, toNavigationLink} from './sidebars/utils';
-import {createDocsByIdIndex} from './docs';
 
 function getCategoryGeneratedIndexMetadata({
   category,

package/src/cli.ts

@@ -5,20 +5,21 @@
  * LICENSE file in the root directory of this source tree.
  */
 
+import fs from 'fs-extra';
+import path from 'path';
+import logger from '@docusaurus/logger';
+import {DEFAULT_PLUGIN_ID} from '@docusaurus/utils';
 import {
   getVersionsFilePath,
   getVersionDocsDirPath,
   getVersionSidebarsPath,
   getDocsDirPathLocalized,
+  readVersionsFile,
 } from './versions/files';
 import {validateVersionName} from './versions/validation';
-import fs from 'fs-extra';
-import path from 'path';
-import type {PluginOptions} from '@docusaurus/plugin-content-docs';
 import {loadSidebarsFileUnsafe} from './sidebars';
 import {CURRENT_VERSION_NAME} from './constants';
-import {DEFAULT_PLUGIN_ID} from '@docusaurus/utils';
-import logger from '@docusaurus/logger';
+import type {PluginOptions} from '@docusaurus/plugin-content-docs';
 import type {LoadContext} from '@docusaurus/types';
 
 async function createVersionedSidebarFile({
@@ -53,7 +54,7 @@ async function createVersionedSidebarFile({
 
 // Tests depend on non-default export for mocking.
 export async function cliDocsVersionCommand(
-  version: string,
+  version: unknown,
   {id: pluginId, path: docsPath, sidebarPath}: PluginOptions,
   {siteDir, i18n}: LoadContext,
 ): Promise<void> {
@@ -64,17 +65,12 @@ export async function cliDocsVersionCommand(
 
   try {
     validateVersionName(version);
-  } catch (e) {
+  } catch (err) {
     logger.info`${pluginIdLogPrefix}: Invalid version name provided. Try something like: 1.0.0`;
-    throw e;
+    throw err;
   }
 
-  // Load existing versions.
-  let versions = [];
-  const versionsJSONFile = getVersionsFilePath(siteDir, pluginId);
-  if (await fs.pathExists(versionsJSONFile)) {
-    versions = await fs.readJSON(versionsJSONFile);
-  }
+  const versions = (await readVersionsFile(siteDir, pluginId)) ?? [];
 
   // Check if version already exists.
   if (versions.includes(version)) {
@@ -137,7 +133,7 @@ export async function cliDocsVersionCommand(
   // Update versions.json file.
   versions.unshift(version);
   await fs.outputFile(
-    versionsJSONFile,
+    getVersionsFilePath(siteDir, pluginId),
     `${JSON.stringify(versions, null, 2)}\n`,
   );
 

package/src/client/docsClientUtils.ts

@@ -126,6 +126,6 @@ export function getDocVersionSuggestions(
   const latestVersion = getLatestVersion(data);
   const activeDocContext = getActiveDocContext(data, pathname);
   const latestDocSuggestion: GlobalDoc | undefined =
-    activeDocContext?.alternateDocVersions[latestVersion.name];
+    activeDocContext.alternateDocVersions[latestVersion.name];
   return {latestDocSuggestion, latestVersionSuggestion: latestVersion};
 }

package/src/client/index.ts

@@ -34,8 +34,11 @@ const StableEmptyObject = {};
 // In blog-only mode, docs hooks are still used by the theme. We need a fail-
 // safe fallback when the docs plugin is not in use
 export const useAllDocsData = (): {[pluginId: string]: GlobalPluginData} =>
-  useAllPluginInstancesData('docusaurus-plugin-content-docs') ??
-  StableEmptyObject;
+  (useAllPluginInstancesData('docusaurus-plugin-content-docs') as
+    | {
+        [pluginId: string]: GlobalPluginData;
+      }
+    | undefined) ?? StableEmptyObject;
 
 export const useDocsData = (pluginId: string | undefined): GlobalPluginData =>
   usePluginData('docusaurus-plugin-content-docs', pluginId, {

package/src/docs.ts

@@ -19,15 +19,12 @@ import {
   Globby,
   normalizeFrontMatterTags,
 } from '@docusaurus/utils';
-import type {LoadContext} from '@docusaurus/types';
 
 import {getFileLastUpdate} from './lastUpdate';
-import type {DocFile} from './types';
 import getSlug from './slug';
 import {CURRENT_VERSION_NAME} from './constants';
 import {stripPathNumberPrefixes} from './numberPrefix';
 import {validateDocFrontMatter} from './frontMatter';
-import type {SidebarsUtils} from './sidebars/utils';
 import {toDocNavigationLink, toNavigationLink} from './sidebars/utils';
 import type {
   MetadataOptions,
@@ -41,6 +38,9 @@ import type {
   DocFrontMatter,
   LoadedVersion,
 } from '@docusaurus/plugin-content-docs';
+import type {LoadContext} from '@docusaurus/types';
+import type {SidebarsUtils} from './sidebars/utils';
+import type {DocFile} from './types';
 
 type LastUpdateOptions = Pick<
   PluginOptions,

package/src/globalData.ts

@@ -6,7 +6,6 @@
  */
 
 import _ from 'lodash';
-import type {Sidebars} from './sidebars/types';
 import {getMainDocId} from './docs';
 import type {FullVersion} from './types';
 import type {
@@ -18,6 +17,7 @@ import type {
   GlobalSidebar,
   GlobalDoc,
 } from '@docusaurus/plugin-content-docs/client';
+import type {Sidebars} from './sidebars/types';
 
 function toGlobalDataDoc(doc: DocMetadata): GlobalDoc {
   return {

package/src/index.ts

@@ -6,7 +6,8 @@
  */
 
 import path from 'path';
-
+import _ from 'lodash';
+import logger from '@docusaurus/logger';
 import {
   normalizeUrl,
   docuHash,
@@ -19,20 +20,15 @@ import {
   createSlugger,
   DEFAULT_PLUGIN_ID,
 } from '@docusaurus/utils';
-import type {LoadContext, Plugin} from '@docusaurus/types';
 import {loadSidebars, resolveSidebarPathOption} from './sidebars';
 import {CategoryMetadataFilenamePattern} from './sidebars/generator';
-import type {DocEnv} from './docs';
-import {readVersionDocs, processDocMetadata, addDocNavigation} from './docs';
+import {
+  readVersionDocs,
+  processDocMetadata,
+  addDocNavigation,
+  type DocEnv,
+} from './docs';
 import {readVersionsMetadata} from './versions';
-import type {
-  SourceToPermalink,
-  DocFile,
-  DocsMarkdownOption,
-  VersionTag,
-  FullVersion,
-} from './types';
-import type {RuleSetRule} from 'webpack';
 import {cliDocsVersionCommand} from './cli';
 import {VERSIONS_JSON_FILE} from './constants';
 import {toGlobalDataVersion} from './globalData';
@@ -42,9 +38,10 @@ import {
   translateLoadedContent,
   getLoadedContentTranslationFiles,
 } from './translations';
-import logger from '@docusaurus/logger';
 import {getVersionTags} from './tags';
 import {createVersionRoutes} from './routes';
+import {createSidebarsUtils} from './sidebars/utils';
+
 import type {
   PropTagsListPage,
   PluginOptions,
@@ -54,8 +51,15 @@ import type {
   LoadedContent,
   LoadedVersion,
 } from '@docusaurus/plugin-content-docs';
-import {createSidebarsUtils} from './sidebars/utils';
-import _ from 'lodash';
+import type {LoadContext, Plugin} from '@docusaurus/types';
+import type {
+  SourceToPermalink,
+  DocFile,
+  DocsMarkdownOption,
+  VersionTag,
+  FullVersion,
+} from './types';
+import type {RuleSetRule} from 'webpack';
 
 export default async function pluginContentDocs(
   context: LoadContext,
@@ -96,7 +100,7 @@ export default async function pluginContentDocs(
         .command(command)
         .arguments('<version>')
         .description(commandDescription)
-        .action((version) => {
+        .action((version: unknown) => {
           cliDocsVersionCommand(version, options, context);
         });
     },
@@ -139,7 +143,7 @@ export default async function pluginContentDocs(
             )}".`,
           );
         }
-        async function processVersionDoc(docFile: DocFile) {
+        function processVersionDoc(docFile: DocFile) {
           return processDocMetadata({
             docFile,
             versionMetadata,

package/src/markdown/index.ts

@@ -16,5 +16,5 @@ export default function markdownLoader(
   const fileString = source;
   const callback = this.async();
   const options = this.getOptions();
-  return callback?.(null, linkify(fileString, this.resourcePath, options));
+  return callback(null, linkify(fileString, this.resourcePath, options));
 }

package/src/markdown/linkify.ts

@@ -5,8 +5,8 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import type {DocsMarkdownOption} from '../types';
 import {replaceMarkdownLinks, getContentPathList} from '@docusaurus/utils';
+import type {DocsMarkdownOption} from '../types';
 
 function getVersion(filePath: string, options: DocsMarkdownOption) {
   const versionFound = options.versionsMetadata.find((version) =>

package/src/options.ts

@@ -5,7 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import type {PluginOptions, Options} from '@docusaurus/plugin-content-docs';
+import logger from '@docusaurus/logger';
 import {
   Joi,
   RemarkPluginsSchema,
@@ -14,15 +14,14 @@ import {
   URISchema,
 } from '@docusaurus/utils-validation';
 import {GlobExcludeDefault} from '@docusaurus/utils';
-
-import type {OptionValidationContext} from '@docusaurus/types';
-import logger from '@docusaurus/logger';
 import admonitions from 'remark-admonitions';
 import {DefaultSidebarItemsGenerator} from './sidebars/generator';
 import {
   DefaultNumberPrefixParser,
   DisabledNumberPrefixParser,
 } from './numberPrefix';
+import type {OptionValidationContext} from '@docusaurus/types';
+import type {PluginOptions, Options} from '@docusaurus/plugin-content-docs';
 
 export const DEFAULT_OPTIONS: Omit<PluginOptions, 'id' | 'sidebarPath'> = {
   path: 'docs', // Path to data on filesystem, relative to site dir.
@@ -99,7 +98,7 @@ const OptionsSchema = Joi.object<PluginOptions>({
       Joi.function(),
       // Convert boolean values to functions
       Joi.alternatives().conditional(Joi.boolean(), {
-        then: Joi.custom((val) =>
+        then: Joi.custom((val: boolean) =>
           val ? DefaultNumberPrefixParser : DisabledNumberPrefixParser,
         ),
       }),
@@ -166,7 +165,7 @@ export function validateOptions({
     }
   }
 
-  const normalizedOptions = validate(OptionsSchema, options) as PluginOptions;
+  const normalizedOptions = validate(OptionsSchema, options);
 
   if (normalizedOptions.admonitions) {
     normalizedOptions.remarkPlugins = normalizedOptions.remarkPlugins.concat([

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

@@ -5,6 +5,8 @@
  * LICENSE file in the root directory of this source tree.
  */
 
+/// <reference types="@docusaurus/module-type-aliases" />
+
 declare module '@docusaurus/plugin-content-docs' {
   import type {MDXOptions} from '@docusaurus/mdx-loader';
   import type {
@@ -15,7 +17,7 @@ declare module '@docusaurus/plugin-content-docs' {
     Tag,
   } from '@docusaurus/utils';
   import type {Plugin, LoadContext} from '@docusaurus/types';
-  import type {Required} from 'utility-types';
+  import type {Overwrite, Required} from 'utility-types';
 
   export type Assets = {
     image?: string;
@@ -204,7 +206,22 @@ declare module '@docusaurus/plugin-content-docs' {
        */
       tagsBasePath: string;
     };
-  export type Options = Partial<PluginOptions>;
+  export type Options = Partial<
+    Overwrite<
+      PluginOptions,
+      {
+        /**
+         * Custom parsing logic to extract number prefixes from file names. Use
+         * `false` to disable this behavior and leave the docs untouched, and
+         * `true` to use the default parser.
+         *
+         * @param filename One segment of the path, without any slashes.
+         * @see https://docusaurus.io/docs/sidebar#using-number-prefixes
+         */
+        numberPrefixParser: PluginOptions['numberPrefixParser'] | boolean;
+      }
+    >
+  >;
   export type SidebarsConfig = import('./sidebars/types').SidebarsConfig;
 
   export type VersionMetadata = ContentPaths & {

package/src/props.ts

@@ -5,6 +5,8 @@
  * LICENSE file in the root directory of this source tree.
  */
 
+import _ from 'lodash';
+import {createDocsByIdIndex} from './docs';
 import type {VersionTag} from './types';
 import type {
   SidebarItemDoc,
@@ -24,8 +26,6 @@ import type {
   DocMetadata,
   LoadedVersion,
 } from '@docusaurus/plugin-content-docs';
-import _ from 'lodash';
-import {createDocsByIdIndex} from './docs';
 
 export function toSidebarsProp(loadedVersion: LoadedVersion): PropSidebars {
   const docsById = createDocsByIdIndex(loadedVersion.docs);
@@ -51,7 +51,7 @@ Available document ids are:
     } = docMetadata;
     return {
       type: 'link',
-      label: sidebarLabel || item.label || title,
+      label: sidebarLabel ?? item.label ?? title,
       href: permalink,
       className: item.className,
       customProps:

package/src/routes.ts

@@ -5,15 +5,15 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import type {PluginContentLoadedActions, RouteConfig} from '@docusaurus/types';
+import logger from '@docusaurus/logger';
 import {docuHash, createSlugger} from '@docusaurus/utils';
+import {toVersionMetadataProp} from './props';
+import type {PluginContentLoadedActions, RouteConfig} from '@docusaurus/types';
 import type {FullVersion} from './types';
 import type {
   CategoryGeneratedIndexMetadata,
   DocMetadata,
 } from '@docusaurus/plugin-content-docs';
-import {toVersionMetadataProp} from './props';
-import logger from '@docusaurus/logger';
 
 export async function createCategoryGeneratedIndexRoutes({
   version,

package/src/sidebars/README.md

@@ -6,4 +6,5 @@ This part is very complicated and hard to navigate. Sidebars are loaded through
 2. **Normalization**. The shorthands are expanded. This step is very lenient about the sidebars' shapes. Returns `NormalizedSidebars`.
 3. **Validation**. The normalized sidebars are validated. This step happens after normalization, because the normalized sidebars are easier to validate, and allows us to repeatedly validate & generate in the future.
 4. **Generation**. This step is done through the "processor" (naming is hard). The `autogenerated` items are unwrapped. In the future, steps 3 and 4 may be repeatedly done until all autogenerated items are unwrapped. Returns `ProcessedSidebars`.
+   - **Important**: this step should only care about unwrapping autogenerated items, not filtering them, writing additional metadata, applying defaults, etc.—everything will be handled in the post-processor. Important because the generator is exposed to the end-user and we want it to be easy to be reasoned about.
 5. **Post-processing**. Defaults are applied (collapsed states), category links are resolved, empty categories are flattened. Returns `Sidebars`.

package/src/sidebars/generator.ts

@@ -5,6 +5,11 @@
  * LICENSE file in the root directory of this source tree.
  */
 
+import path from 'path';
+import _ from 'lodash';
+import logger from '@docusaurus/logger';
+import {addTrailingSlash} from '@docusaurus/utils';
+import {createDocsByIdIndex, toCategoryIndexMatcherParam} from '../docs';
 import type {
   SidebarItemDoc,
   SidebarItemsGenerator,
@@ -13,11 +18,6 @@ import type {
   NormalizedSidebarItem,
   SidebarItemCategoryLinkConfig,
 } from './types';
-import _ from 'lodash';
-import {addTrailingSlash} from '@docusaurus/utils';
-import logger from '@docusaurus/logger';
-import path from 'path';
-import {createDocsByIdIndex, toCategoryIndexMatcherParam} from '../docs';
 
 const BreadcrumbSeparator = '/';
 
@@ -46,7 +46,7 @@ type Dir = {
 };
 
 // Comment for this feature: https://github.com/facebook/docusaurus/issues/3464#issuecomment-818670449
-export const DefaultSidebarItemsGenerator: SidebarItemsGenerator = async ({
+export const DefaultSidebarItemsGenerator: SidebarItemsGenerator = ({
   numberPrefixParser,
   isCategoryIndex,
   docs: allDocs,

package/src/sidebars/index.ts

@@ -6,19 +6,19 @@
  */
 
 import fs from 'fs-extra';
+import path from 'path';
+import _ from 'lodash';
+import logger from '@docusaurus/logger';
+import {Globby} from '@docusaurus/utils';
+import Yaml from 'js-yaml';
+import combinePromises from 'combine-promises';
 import importFresh from 'import-fresh';
-import type {SidebarsConfig, Sidebars, SidebarProcessorParams} from './types';
 import {validateSidebars, validateCategoryMetadataFile} from './validation';
 import {normalizeSidebars} from './normalization';
 import {processSidebars} from './processor';
 import {postProcessSidebars} from './postProcessor';
-import path from 'path';
-import {Globby} from '@docusaurus/utils';
-import logger from '@docusaurus/logger';
 import type {PluginOptions} from '@docusaurus/plugin-content-docs';
-import Yaml from 'js-yaml';
-import _ from 'lodash';
-import combinePromises from 'combine-promises';
+import type {SidebarsConfig, Sidebars, SidebarProcessorParams} from './types';
 
 export const DefaultSidebars: SidebarsConfig = {
   defaultSidebar: [