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

package/src/lastUpdate.ts

@@ -5,13 +5,11 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import shell from 'shelljs';
 import logger from '@docusaurus/logger';
+import {getFileCommitDate, GitNotFoundError} from '@docusaurus/utils';
 
 type FileLastUpdateData = {timestamp?: number; author?: string};
 
-const GIT_COMMIT_TIMESTAMP_AUTHOR_REGEX = /^(\d+),(.+)$/;
-
 let showedGitRequirementError = false;
 
 export async function getFileLastUpdate(
@@ -20,41 +18,22 @@ export async function getFileLastUpdate(
   if (!filePath) {
     return null;
   }
-  function getTimestampAndAuthor(str: string): FileLastUpdateData | null {
-    if (!str) {
-      return null;
-    }
-
-    const temp = str.match(GIT_COMMIT_TIMESTAMP_AUTHOR_REGEX);
-    return !temp || temp.length < 3
-      ? null
-      : {timestamp: +temp[1], author: temp[2]};
-  }
 
   // Wrap in try/catch in case the shell commands fail
   // (e.g. project doesn't use Git, etc).
   try {
-    if (!shell.which('git')) {
-      if (!showedGitRequirementError) {
-        showedGitRequirementError = true;
-        logger.warn('Sorry, the docs plugin last update options require Git.');
-      }
-
-      return null;
-    }
-
-    const result = shell.exec(`git log -1 --format=%ct,%an "${filePath}"`, {
-      silent: true,
+    const result = getFileCommitDate(filePath, {
+      age: 'newest',
+      includeAuthor: true,
     });
-    if (result.code !== 0) {
-      throw new Error(
-        `Retrieval of git history failed at "${filePath}" with exit code ${result.code}: ${result.stderr}`,
-      );
+    return {timestamp: result.timestamp, author: result.author};
+  } catch (err) {
+    if (err instanceof GitNotFoundError && !showedGitRequirementError) {
+      logger.warn('Sorry, the docs plugin last update options require Git.');
+      showedGitRequirementError = true;
+    } else {
+      logger.error(err);
     }
-    return getTimestampAndAuthor(result.stdout.trim());
-  } catch (e) {
-    logger.error(e);
+    return null;
   }
-
-  return null;
 }

package/src/numberPrefix.ts

@@ -8,16 +8,17 @@
 import type {NumberPrefixParser} from '@docusaurus/plugin-content-docs';
 
 // Best-effort to avoid parsing some patterns as number prefix
-const IgnoredPrefixPatterns = (function () {
+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}))?)(.*)$/;
+    /^(?:\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 his own NumberPrefixParser if he wants 8.0 to be interpreted as a float
-  const VersionLikePrefixRegex = /^(\d+[-_.]\d+)(.*)$/;
+  // 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}`,

package/src/options.ts

@@ -55,6 +55,7 @@ export const DEFAULT_OPTIONS: Omit<PluginOptions, 'id' | 'sidebarPath'> = {
   editLocalizedFiles: false,
   sidebarCollapsible: true,
   sidebarCollapsed: true,
+  breadcrumbs: true,
 };
 
 const VersionOptionsSchema = Joi.object({
@@ -139,6 +140,7 @@ export const OptionsSchema = Joi.object({
   disableVersioning: Joi.bool().default(DEFAULT_OPTIONS.disableVersioning),
   lastVersion: Joi.string().optional(),
   versions: VersionsOptionsSchema,
+  breadcrumbs: Joi.bool().default(DEFAULT_OPTIONS.breadcrumbs),
 });
 
 export function validateOptions({
@@ -148,8 +150,9 @@ export function validateOptions({
   let options = userOptions;
 
   if (options.sidebarCollapsible === false) {
-    // When sidebarCollapsible=false and sidebarCollapsed=undefined, we don't want to have the inconsistency warning
-    // We let options.sidebarCollapsible become the default value for options.sidebarCollapsed
+    // When sidebarCollapsible=false and sidebarCollapsed=undefined, we don't
+    // want to have the inconsistency warning. We let options.sidebarCollapsible
+    // become the default value for options.sidebarCollapsed
     if (typeof options.sidebarCollapsed === 'undefined') {
       options = {
         ...options,

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

@@ -8,6 +8,10 @@
 declare module '@docusaurus/plugin-content-docs' {
   import type {RemarkAndRehypePluginOptions} from '@docusaurus/mdx-loader';
 
+  export interface Assets {
+    image?: string;
+  }
+
   export type NumberPrefixParser = (filename: string) => {
     filename: string;
     numberPrefix?: number;
@@ -38,6 +42,7 @@ declare module '@docusaurus/plugin-content-docs' {
     showLastUpdateTime?: boolean;
     showLastUpdateAuthor?: boolean;
     numberPrefixParser: NumberPrefixParser;
+    breadcrumbs: boolean;
   };
 
   export type PathOptions = {
@@ -45,7 +50,8 @@ declare module '@docusaurus/plugin-content-docs' {
     sidebarPath?: string | false | undefined;
   };
 
-  // TODO support custom version banner? {type: "error", content: "html content"}
+  // TODO support custom version banner?
+  // {type: "error", content: "html content"}
   export type VersionBanner = 'unreleased' | 'unmaintained';
   export type VersionOptions = {
     path?: string;
@@ -125,6 +131,8 @@ declare module '@docusaurus/plugin-content-docs' {
   export type PropSidebarItemCategory =
     import('./sidebars/types').PropSidebarItemCategory;
   export type PropSidebarItem = import('./sidebars/types').PropSidebarItem;
+  export type PropSidebarBreadcrumbsItem =
+    import('./sidebars/types').PropSidebarBreadcrumbsItem;
   export type PropSidebar = import('./sidebars/types').PropSidebar;
   export type PropSidebars = import('./sidebars/types').PropSidebars;
 
@@ -155,6 +163,7 @@ declare module '@theme/DocItem' {
   import type {
     PropNavigationLink,
     PropVersionMetadata,
+    Assets,
   } from '@docusaurus/plugin-content-docs';
 
   export type DocumentRoute = {
@@ -200,32 +209,12 @@ declare module '@theme/DocItem' {
       readonly metadata: Metadata;
       readonly toc: readonly TOCItem[];
       readonly contentTitle: string | undefined;
+      readonly assets: Assets;
       (): JSX.Element;
     };
   }
 
-  const DocItem: (props: Props) => JSX.Element;
-  export default DocItem;
-}
-
-declare module '@theme/DocCard' {
-  import type {PropSidebarItem} from '@docusaurus/plugin-content-docs';
-
-  export interface Props {
-    readonly item: PropSidebarItem;
-  }
-
-  export default function DocCard(props: Props): JSX.Element;
-}
-
-declare module '@theme/DocCardList' {
-  import type {PropSidebarItem} from '@docusaurus/plugin-content-docs';
-
-  export interface Props {
-    readonly items: PropSidebarItem[];
-  }
-
-  export default function DocCardList(props: Props): JSX.Element;
+  export default function DocItem(props: Props): JSX.Element;
 }
 
 declare module '@theme/DocCategoryGeneratedIndexPage' {
@@ -240,12 +229,6 @@ declare module '@theme/DocCategoryGeneratedIndexPage' {
   ): JSX.Element;
 }
 
-declare module '@theme/DocItemFooter' {
-  import type {Props} from '@theme/DocItem';
-
-  export default function DocItemFooter(props: Props): JSX.Element;
-}
-
 declare module '@theme/DocTagsListPage' {
   import type {PropTagsListPage} from '@docusaurus/plugin-content-docs';
 
@@ -262,20 +245,8 @@ declare module '@theme/DocTagDocListPage' {
   export default function DocTagDocListPage(props: Props): JSX.Element;
 }
 
-declare module '@theme/DocVersionBanner' {
-  export interface Props {
-    readonly className?: string;
-  }
-
-  export default function DocVersionBanner(props: Props): JSX.Element;
-}
-
-declare module '@theme/DocVersionBadge' {
-  export interface Props {
-    readonly className?: string;
-  }
-
-  export default function DocVersionBadge(props: Props): JSX.Element;
+declare module '@theme/DocBreadcrumbs' {
+  export default function DocBreadcrumbs(): JSX.Element;
 }
 
 declare module '@theme/DocPage' {
@@ -292,23 +263,7 @@ declare module '@theme/DocPage' {
     };
   }
 
-  const DocPage: (props: Props) => JSX.Element;
-  export default DocPage;
-}
-
-declare module '@theme/Seo' {
-  import type {ReactNode} from 'react';
-
-  export interface Props {
-    readonly title?: string;
-    readonly description?: string;
-    readonly keywords?: readonly string[] | string;
-    readonly image?: string;
-    readonly children?: ReactNode;
-  }
-
-  const Seo: (props: Props) => JSX.Element;
-  export default Seo;
+  export default function DocPage(props: Props): JSX.Element;
 }
 
 // TODO until TS supports exports field... hope it's in 4.6
@@ -350,6 +305,7 @@ declare module '@docusaurus/plugin-content-docs/client' {
   export type GlobalPluginData = {
     path: string;
     versions: GlobalVersion[];
+    breadcrumbs: boolean;
   };
   export type DocVersionSuggestions = {
     // suggest the latest version

package/src/props.ts

@@ -22,7 +22,7 @@ import type {
   PropTagDocListDoc,
   PropSidebarItemLink,
 } from '@docusaurus/plugin-content-docs';
-import {compact, keyBy, mapValues} from 'lodash';
+import _ from 'lodash';
 import {createDocsByIdIndex} from './docs';
 
 export function toSidebarsProp(loadedVersion: LoadedVersion): PropSidebars {
@@ -52,7 +52,8 @@ Available document ids are:
       label: sidebarLabel || item.label || title,
       href: permalink,
       className: item.className,
-      customProps: item.customProps,
+      customProps:
+        item.customProps ?? docMetadata.frontMatter.sidebar_custom_props,
       docId: docMetadata.unversionedId,
     };
   };
@@ -92,18 +93,22 @@ Available document ids are:
   // Transform the sidebar so that all sidebar item will be in the
   // form of 'link' or 'category' only.
   // This is what will be passed as props to the UI component.
-  return mapValues(loadedVersion.sidebars, (items) => items.map(normalizeItem));
+  return _.mapValues(loadedVersion.sidebars, (items) =>
+    items.map(normalizeItem),
+  );
 }
 
 function toVersionDocsProp(loadedVersion: LoadedVersion): PropVersionDocs {
-  return mapValues(
-    keyBy(loadedVersion.docs, (doc) => doc.unversionedId),
-    (doc) => ({
-      id: doc.unversionedId,
-      title: doc.title,
-      description: doc.description,
-      sidebar: doc.sidebar,
-    }),
+  return Object.fromEntries(
+    loadedVersion.docs.map((doc) => [
+      doc.unversionedId,
+      {
+        id: doc.unversionedId,
+        title: doc.title,
+        description: doc.description,
+        sidebar: doc.sidebar,
+      },
+    ]),
   );
 }
 
@@ -134,7 +139,7 @@ export function toTagDocListProp({
   docs: Pick<DocMetadata, 'id' | 'title' | 'description' | 'permalink'>[];
 }): PropTagDocList {
   function toDocListProp(): PropTagDocListDoc[] {
-    const list = compact(
+    const list = _.compact(
       tag.docIds.map((id) => docs.find((doc) => doc.id === id)),
     );
     // Sort docs by title

package/src/routes.ts

@@ -73,7 +73,8 @@ export async function createCategoryGeneratedIndexRoutes({
       modules: {
         categoryGeneratedIndex: aliasedSource(propData),
       },
-      // Same as doc, this sidebar route attribute permits to associate this subpage to the given sidebar
+      // Same as doc, this sidebar route attribute permits to associate this
+      // subpage to the given sidebar
       ...(sidebar && {sidebar}),
     };
   }
@@ -109,7 +110,8 @@ export async function createDocRoutes({
           content: metadataItem.source,
         },
         // Because the parent (DocPage) comp need to access it easily
-        // This permits to render the sidebar once without unmount/remount when navigating (and preserve sidebar state)
+        // This permits to render the sidebar once without unmount/remount when
+        // navigating (and preserve sidebar state)
         ...(metadataItem.sidebar && {
           sidebar: metadataItem.sidebar,
         }),
@@ -176,8 +178,8 @@ export async function createVersionRoutes({
 
   try {
     return await doCreateVersionRoutes(loadedVersion);
-  } catch (e) {
+  } catch (err) {
     logger.error`Can't create version routes for version name=${loadedVersion.versionName}`;
-    throw e;
+    throw err;
   }
 }

package/src/server-export.ts

@@ -0,0 +1,24 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+// APIs available to Node.js
+export {
+  CURRENT_VERSION_NAME,
+  VERSIONED_DOCS_DIR,
+  VERSIONED_SIDEBARS_DIR,
+  VERSIONS_JSON_FILE,
+} from './constants';
+
+export {
+  filterVersions,
+  getDefaultVersionBanner,
+  getVersionBadge,
+  getVersionBanner,
+  getVersionsFilePath,
+  readVersionsFile,
+  readVersionNames,
+} from './versions';

package/src/sidebars/README.md

@@ -0,0 +1,9 @@
+# Sidebars
+
+This part is very complicated and hard to navigate. Sidebars are loaded through the following steps:
+
+1. **Loading**. The sidebars file is read. Returns `SidebarsConfig`.
+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`.
+5. **Post-processing**. Defaults are applied (collapsed states), category links are resolved, empty categories are flattened. Returns `Sidebars`.

package/src/sidebars/generator.ts

@@ -6,25 +6,17 @@
  */
 
 import type {
-  SidebarItem,
   SidebarItemDoc,
-  SidebarItemCategory,
   SidebarItemsGenerator,
   SidebarItemsGeneratorDoc,
-  SidebarItemCategoryLink,
+  NormalizedSidebarItemCategory,
+  NormalizedSidebarItem,
   SidebarItemCategoryLinkConfig,
 } from './types';
-import {sortBy, last} from 'lodash';
-import {
-  addTrailingSlash,
-  posixPath,
-  findAsyncSequential,
-} from '@docusaurus/utils';
+import _ from 'lodash';
+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 = '/';
@@ -33,72 +25,31 @@ const docIdPrefix = '$doc$/';
 
 // Just an alias to the make code more explicit
 function getLocalDocId(docId: string): string {
-  return last(docId.split('/'))!;
+  return _.last(docId.split('/'))!;
 }
 
 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;
-
-  // 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};
 
 /**
  * A representation of the fs structure. For each object entry:
- * If it's a folder, the key is the directory name, and value is the directory content;
- * If it's a doc file, the key is the doc id prefixed with '$doc$/', and value is null
+ * If it's a folder, the key is the directory name, and value is the directory
+ * content; If it's a doc file, the key is the doc id prefixed with '$doc$/',
+ * and value is null
  */
 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 route path segment 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,
   isCategoryIndex,
   docs: allDocs,
-  options,
   item: {dirName: autogenDir},
-  version,
+  categoriesMetadata,
 }) => {
   const docsById = createDocsByIdIndex(allDocs);
   const findDoc = (docId: string): SidebarItemsGeneratorDoc | undefined =>
@@ -142,7 +93,8 @@ export const DefaultSidebarItemsGenerator: SidebarItemsGenerator = async ({
    * Step 2. Turn the linear file list into a tree structure.
    */
   function treeify(docs: SidebarItemsGeneratorDoc[]): Dir {
-    // Get the category breadcrumb of a doc (relative to the dir of the autogenerated sidebar item)
+    // Get the category breadcrumb of a doc (relative to the dir of the
+    // autogenerated sidebar item)
     // autogenDir=a/b and docDir=a/b/c/d => returns [c, d]
     // autogenDir=a/b and docDir=a/b => returns []
     // TODO: try to use path.relative()
@@ -169,10 +121,12 @@ export const DefaultSidebarItemsGenerator: SidebarItemsGenerator = async ({
   }
 
   /**
-   * Step 3. Recursively transform the tree-like file structure to sidebar items.
+   * Step 3. Recursively transform the tree-like structure to sidebar items.
    * (From a record to an array of items, akin to normalizing shorthand)
    */
-  function generateSidebar(fsModel: Dir): Promise<WithPosition<SidebarItem>[]> {
+  function generateSidebar(
+    fsModel: Dir,
+  ): Promise<WithPosition<NormalizedSidebarItem>[]> {
     function createDocItem(id: string): WithPosition<SidebarItemDoc> {
       const {
         sidebarPosition: position,
@@ -182,7 +136,8 @@ export const DefaultSidebarItemsGenerator: SidebarItemsGenerator = async ({
         type: 'doc',
         id,
         position,
-        // We don't want these fields to magically appear in the generated sidebar
+        // We don't want these fields to magically appear in the generated
+        // sidebar
         ...(label !== undefined && {label}),
         ...(className !== undefined && {className}),
       };
@@ -191,9 +146,9 @@ export const DefaultSidebarItemsGenerator: SidebarItemsGenerator = async ({
       dir: Dir,
       fullPath: string,
       folderName: string,
-    ): Promise<WithPosition<SidebarItemCategory>> {
-      const categoryPath = path.join(version.contentPath, autogenDir, fullPath);
-      const categoryMetadata = await readCategoryMetadataFile(categoryPath);
+    ): Promise<WithPosition<NormalizedSidebarItemCategory>> {
+      const categoryMetadata =
+        categoriesMetadata[posixPath(path.join(autogenDir, fullPath))];
       const className = categoryMetadata?.className;
       const {filename, numberPrefix} = numberPrefixParser(folderName);
       const allItems = await Promise.all(
@@ -206,44 +161,44 @@ export const DefaultSidebarItemsGenerator: SidebarItemsGenerator = async ({
       // using the "local id" (myDoc) or "qualified id" (dirName/myDoc)
       function findDocByLocalId(localId: string): SidebarItemDoc | undefined {
         return allItems.find(
-          (item) => item.type === 'doc' && getLocalDocId(item.id) === localId,
-        ) as SidebarItemDoc | undefined;
+          (item): item is SidebarItemDoc =>
+            item.type === 'doc' && getLocalDocId(item.id) === localId,
+        );
       }
 
       function findConventionalCategoryDocLink(): SidebarItemDoc | undefined {
-        return allItems.find((item) => {
+        return allItems.find((item): item is SidebarItemDoc => {
           if (item.type !== 'doc') {
             return false;
           }
           const doc = getDoc(item.id);
           return isCategoryIndex(toCategoryIndexMatcherParam(doc));
-        }) as SidebarItemDoc | undefined;
+        });
       }
 
       function getCategoryLinkedDocId(): string | undefined {
         const link = categoryMetadata?.link;
-        if (link) {
-          if (link.type === 'doc') {
+        if (link !== undefined) {
+          if (link && link.type === 'doc') {
             return findDocByLocalId(link.id)?.id || getDoc(link.id).id;
-          } else {
-            // We don't continue for other link types on purpose!
-            // IE if user decide to use type "generated-index", we should not pick a README.md file as the linked doc
-            return undefined;
           }
+          // 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
+        // Apply default convention to pick index.md, README.md or
+        // <categoryName>.md as the category doc
         return findConventionalCategoryDocLink()?.id;
       }
 
       const categoryLinkedDocId = getCategoryLinkedDocId();
 
-      const link: SidebarItemCategoryLink | undefined = categoryLinkedDocId
-        ? {
-            type: 'doc',
-            id: categoryLinkedDocId, // We "remap" a potentially "local id" to a "qualified id"
-          }
-        : // TODO typing issue
-          (categoryMetadata?.link as SidebarItemCategoryLink | undefined);
+      const link: SidebarItemCategoryLinkConfig | null | undefined =
+        categoryLinkedDocId
+          ? {
+              type: 'doc',
+              id: categoryLinkedDocId, // 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(
@@ -253,9 +208,8 @@ export const DefaultSidebarItemsGenerator: SidebarItemsGenerator = async ({
       return {
         type: 'category',
         label: categoryMetadata?.label ?? filename,
-        collapsible:
-          categoryMetadata?.collapsible ?? options.sidebarCollapsible,
-        collapsed: categoryMetadata?.collapsed ?? options.sidebarCollapsed,
+        collapsible: categoryMetadata?.collapsible,
+        collapsed: categoryMetadata?.collapsed,
         position: categoryMetadata?.position ?? numberPrefix,
         ...(className !== undefined && {className}),
         items,
@@ -266,7 +220,7 @@ export const DefaultSidebarItemsGenerator: SidebarItemsGenerator = async ({
       dir: Dir | null, // The directory item to be transformed.
       itemKey: string, // For docs, it's the doc ID; for categories, it's used to generate the next `relativePath`.
       fullPath: string, // `dir`'s full path relative to the autogen dir.
-    ): Promise<WithPosition<SidebarItem>> {
+    ): Promise<WithPosition<NormalizedSidebarItem>> {
       return dir
         ? createCategoryItem(dir, fullPath, itemKey)
         : createDocItem(itemKey.substring(docIdPrefix.length));
@@ -279,26 +233,28 @@ export const DefaultSidebarItemsGenerator: SidebarItemsGenerator = async ({
   }
 
   /**
-   * Step 4. Recursively sort the categories/docs + remove the "position" attribute from final output.
-   * Note: the "position" is only used to sort "inside" a sidebar slice. It is not
-   * used to sort across multiple consecutive sidebar slices (ie a whole Category
-   * composed of multiple autogenerated items)
+   * Step 4. Recursively sort the categories/docs + remove the "position"
+   * attribute from final output. Note: the "position" is only used to sort
+   * "inside" a sidebar slice. It is not used to sort across multiple
+   * consecutive sidebar slices (i.e. a whole category composed of multiple
+   * autogenerated items)
    */
-  function sortItems(sidebarItems: WithPosition<SidebarItem>[]): SidebarItem[] {
+  function sortItems(
+    sidebarItems: WithPosition<NormalizedSidebarItem>[],
+  ): NormalizedSidebarItem[] {
     const processedSidebarItems = sidebarItems.map((item) => {
       if (item.type === 'category') {
         return {...item, items: sortItems(item.items)};
       }
       return item;
     });
-    const sortedSidebarItems = sortBy(
+    const sortedSidebarItems = _.sortBy(
       processedSidebarItems,
       (item) => item.position,
     );
     return sortedSidebarItems.map(({position, ...item}) => item);
   }
   // TODO: the whole code is designed for pipeline operator
-  // return getAutogenDocs() |> treeify |> await generateSidebar(^) |> sortItems;
   const docs = getAutogenDocs();
   const fsModel = treeify(docs);
   const sidebarWithPosition = await generateSidebar(fsModel);