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

package/src/lastUpdate.ts

@@ -6,15 +6,18 @@
  */
 
 import logger from '@docusaurus/logger';
-import {getFileCommitDate, GitNotFoundError} from '@docusaurus/utils';
-
-type FileLastUpdateData = {timestamp?: number; author?: string};
+import {
+  getFileCommitDate,
+  FileNotTrackedError,
+  GitNotFoundError,
+} from '@docusaurus/utils';
 
 let showedGitRequirementError = false;
+let showedFileNotTrackedError = false;
 
 export async function getFileLastUpdate(
   filePath?: string,
-): Promise<FileLastUpdateData | null> {
+): Promise<{timestamp: number; author: string} | null> {
   if (!filePath) {
     return null;
   }
@@ -28,11 +31,20 @@ export async function getFileLastUpdate(
     });
     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;
+    if (err instanceof GitNotFoundError) {
+      if (!showedGitRequirementError) {
+        logger.warn('Sorry, the docs plugin last update options require Git.');
+        showedGitRequirementError = true;
+      }
+    } else if (err instanceof FileNotTrackedError) {
+      if (!showedFileNotTrackedError) {
+        logger.warn(
+          'Cannot infer the update date for some files, as they are not tracked by git.',
+        );
+        showedFileNotTrackedError = true;
+      }
     } else {
-      logger.error(err);
+      logger.warn(err);
     }
     return null;
   }

package/src/markdown/index.ts

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

package/src/markdown/linkify.ts

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

package/src/numberPrefix.ts

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

package/src/options.ts

@@ -5,7 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import type {PluginOptions} from '@docusaurus/plugin-content-docs';
+import type {PluginOptions, Options} from '@docusaurus/plugin-content-docs';
 import {
   Joi,
   RemarkPluginsSchema,
@@ -15,10 +15,7 @@ import {
 } from '@docusaurus/utils-validation';
 import {GlobExcludeDefault} from '@docusaurus/utils';
 
-import type {
-  OptionValidationContext,
-  ValidationResult,
-} from '@docusaurus/types';
+import type {OptionValidationContext} from '@docusaurus/types';
 import logger from '@docusaurus/logger';
 import admonitions from 'remark-admonitions';
 import {DefaultSidebarItemsGenerator} from './sidebars/generator';
@@ -70,7 +67,7 @@ const VersionsOptionsSchema = Joi.object()
   .pattern(Joi.string().required(), VersionOptionsSchema)
   .default(DEFAULT_OPTIONS.versions);
 
-export const OptionsSchema = Joi.object({
+const OptionsSchema = Joi.object<PluginOptions>({
   path: Joi.string().default(DEFAULT_OPTIONS.path),
   editUrl: Joi.alternatives().try(URISchema, Joi.function()),
   editCurrentVersion: Joi.boolean().default(DEFAULT_OPTIONS.editCurrentVersion),
@@ -80,6 +77,7 @@ export const OptionsSchema = Joi.object({
     // .allow('') ""
     .default(DEFAULT_OPTIONS.routeBasePath),
   tagsBasePath: Joi.string().default(DEFAULT_OPTIONS.tagsBasePath),
+  // @ts-expect-error: deprecated
   homePageId: Joi.any().forbidden().messages({
     'any.unknown':
       'The docs plugin option homePageId is not supported anymore. To make a doc the "home", please add "slug: /" in its front matter. See: https://docusaurus.io/docs/next/docs-introduction#home-page-docs',
@@ -146,7 +144,7 @@ export const OptionsSchema = Joi.object({
 export function validateOptions({
   validate,
   options: userOptions,
-}: OptionValidationContext<PluginOptions>): ValidationResult<PluginOptions> {
+}: OptionValidationContext<Options, PluginOptions>): PluginOptions {
   let options = userOptions;
 
   if (options.sidebarCollapsible === false) {
@@ -168,7 +166,7 @@ export function validateOptions({
     }
   }
 
-  const normalizedOptions = validate(OptionsSchema, options);
+  const normalizedOptions = validate(OptionsSchema, options) as PluginOptions;
 
   if (normalizedOptions.admonitions) {
     normalizedOptions.remarkPlugins = normalizedOptions.remarkPlugins.concat([

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

@@ -18,8 +18,14 @@ declare module '@docusaurus/plugin-content-docs' {
   };
 
   export type CategoryIndexMatcherParam = {
+    /** The file name, without extension */
     fileName: string;
+    /**
+     * The list of directories, from lowest level to highest.
+     * If there's no dir name, directories is ['.']
+     */
     directories: string[];
+    /** The extension, with a leading dot */
     extension: string;
   };
   export type CategoryIndexMatcher = (
@@ -62,7 +68,7 @@ declare module '@docusaurus/plugin-content-docs' {
   };
   export type VersionsOptions = {
     lastVersion?: string;
-    versions: Record<string, VersionOptions>;
+    versions: {[versionName: string]: VersionOptions};
     onlyIncludeVersions?: string[];
   };
   export type SidebarOptions = {
@@ -83,7 +89,7 @@ declare module '@docusaurus/plugin-content-docs' {
       docTagDocListComponent: string;
       docTagsListComponent: string;
       docCategoryGeneratedIndexComponent: string;
-      admonitions: Record<string, unknown>;
+      admonitions: {[key: string]: unknown};
       disableVersioning: boolean;
       includeCurrentVersion: boolean;
       sidebarItemsGenerator: import('./sidebars/types').SidebarItemsGeneratorOption;
@@ -185,6 +191,7 @@ declare module '@theme/DocItem' {
   };
 
   export type Metadata = {
+    readonly unversionedId?: string;
     readonly description?: string;
     readonly title?: string;
     readonly permalink?: string;
@@ -275,7 +282,7 @@ declare module '@docusaurus/plugin-content-docs/client' {
   export type ActiveDocContext = {
     activeVersion?: GlobalVersion;
     activeDoc?: GlobalDoc;
-    alternateDocVersions: Record<string, GlobalDoc>;
+    alternateDocVersions: {[versionName: string]: GlobalDoc};
   };
   export type GlobalDoc = {
     id: string;
@@ -290,7 +297,7 @@ declare module '@docusaurus/plugin-content-docs/client' {
     path: string;
     mainDocId: string; // home doc (if docs homepage configured), or first doc
     docs: GlobalDoc[];
-    sidebars?: Record<string, GlobalSidebar>;
+    sidebars?: {[sidebarId: string]: GlobalSidebar};
   };
 
   export type GlobalSidebarLink = {
@@ -315,7 +322,7 @@ declare module '@docusaurus/plugin-content-docs/client' {
   };
   export type GetActivePluginOptions = {failfast?: boolean}; // use fail-fast option if you know for sure one plugin instance is active
 
-  export const useAllDocsData: () => Record<string, GlobalPluginData>;
+  export const useAllDocsData: () => {[pluginId: string]: GlobalPluginData};
   export const useDocsData: (pluginId?: string) => GlobalPluginData;
   export const useActivePlugin: (
     options?: GetActivePluginOptions,

package/src/sidebars/generator.ts

@@ -60,9 +60,9 @@ export const DefaultSidebarItemsGenerator: SidebarItemsGenerator = async ({
     const doc = findDoc(docId);
     if (!doc) {
       throw new Error(
-        `Can't find any doc with id=${docId}.\nAvailable doc ids:\n- ${Object.keys(
-          docsById,
-        ).join('\n- ')}`,
+        `Can't find any doc with ID ${docId}.
+Available doc IDs:
+- ${Object.keys(docsById).join('\n- ')}`,
       );
     }
     return doc;
@@ -158,8 +158,6 @@ export const DefaultSidebarItemsGenerator: SidebarItemsGenerator = async ({
     ): WithPosition<NormalizedSidebarItemCategory> {
       const categoryMetadata =
         categoriesMetadata[posixPath(path.join(autogenDir, fullPath))];
-      const className = categoryMetadata?.className;
-      const {filename, numberPrefix} = numberPrefixParser(folderName);
       const allItems = Object.entries(dir).map(([key, content]) =>
         dirToItem(content, key, `${fullPath}/${key}`),
       );
@@ -183,42 +181,67 @@ export const DefaultSidebarItemsGenerator: SidebarItemsGenerator = async ({
         });
       }
 
-      function getCategoryLinkedDocId(): string | undefined {
-        const link = categoryMetadata?.link;
-        if (link !== undefined) {
-          if (link && link.type === 'doc') {
-            return findDocByLocalId(link.id)?.id || getDoc(link.id).id;
+      // In addition to the ID, this function also retrieves metadata of the
+      // linked doc that could be used as fallback values for category metadata
+      function getCategoryLinkedDocMetadata():
+        | {
+            id: string;
+            position?: number;
+            label?: string;
+            customProps?: {[key: string]: unknown};
+            className?: string;
           }
+        | undefined {
+        const link = categoryMetadata?.link;
+        if (link !== undefined && link?.type !== 'doc') {
           // If a link is explicitly specified, we won't apply conventions
           return undefined;
         }
-        // Apply default convention to pick index.md, README.md or
-        // <categoryName>.md as the category doc
-        return findConventionalCategoryDocLink()?.id;
+        const id = link
+          ? findDocByLocalId(link.id)?.id ?? getDoc(link.id).id
+          : findConventionalCategoryDocLink()?.id;
+        if (!id) {
+          return undefined;
+        }
+        const doc = getDoc(id);
+        return {
+          id,
+          position: doc.sidebarPosition,
+          label: doc.frontMatter.sidebar_label ?? doc.title,
+          customProps: doc.frontMatter.sidebar_custom_props,
+          className: doc.frontMatter.sidebar_class_name,
+        };
       }
-
-      const categoryLinkedDocId = getCategoryLinkedDocId();
-
+      const categoryLinkedDoc = getCategoryLinkedDocMetadata();
       const link: SidebarItemCategoryLinkConfig | null | undefined =
-        categoryLinkedDocId
+        categoryLinkedDoc
           ? {
               type: 'doc',
-              id: categoryLinkedDocId, // We "remap" a potentially "local id" to a "qualified id"
+              id: categoryLinkedDoc.id, // We "remap" a potentially "local id" to a "qualified id"
             }
           : categoryMetadata?.link;
-
       // If a doc is linked, remove it from the category subItems
       const items = allItems.filter(
-        (item) => !(item.type === 'doc' && item.id === categoryLinkedDocId),
+        (item) => !(item.type === 'doc' && item.id === categoryLinkedDoc?.id),
       );
 
+      const className =
+        categoryMetadata?.className ?? categoryLinkedDoc?.className;
+      const customProps =
+        categoryMetadata?.customProps ?? categoryLinkedDoc?.customProps;
+      const {filename, numberPrefix} = numberPrefixParser(folderName);
+
       return {
         type: 'category',
-        label: categoryMetadata?.label ?? filename,
+        label: categoryMetadata?.label ?? categoryLinkedDoc?.label ?? filename,
         collapsible: categoryMetadata?.collapsible,
         collapsed: categoryMetadata?.collapsed,
-        position: categoryMetadata?.position ?? numberPrefix,
+        position:
+          categoryMetadata?.position ??
+          categoryLinkedDoc?.position ??
+          numberPrefix,
         source: folderName,
+        ...(customProps !== undefined && {customProps}),
         ...(className !== undefined && {className}),
         items,
         ...(link && {link}),

package/src/sidebars/index.ts

@@ -49,7 +49,7 @@ async function readCategoriesMetadata(contentPath: string) {
   const categoryToFile = _.groupBy(categoryFiles, path.dirname);
   return combinePromises(
     _.mapValues(categoryToFile, async (files, folder) => {
-      const [filePath] = files;
+      const filePath = files[0]!;
       if (files.length > 1) {
         logger.warn`There are more than one category metadata files for path=${folder}: ${files.join(
           ', ',
@@ -98,16 +98,23 @@ export async function loadSidebars(
   sidebarFilePath: string | false | undefined,
   options: SidebarProcessorParams,
 ): Promise<Sidebars> {
-  const sidebarsConfig = await loadSidebarsFileUnsafe(sidebarFilePath);
-  const normalizedSidebars = normalizeSidebars(sidebarsConfig);
-  validateSidebars(normalizedSidebars);
-  const categoriesMetadata = await readCategoriesMetadata(
-    options.version.contentPath,
-  );
-  const processedSidebars = await processSidebars(
-    normalizedSidebars,
-    categoriesMetadata,
-    options,
-  );
-  return postProcessSidebars(processedSidebars, options);
+  try {
+    const sidebarsConfig = await loadSidebarsFileUnsafe(sidebarFilePath);
+    const normalizedSidebars = normalizeSidebars(sidebarsConfig);
+    validateSidebars(normalizedSidebars);
+    const categoriesMetadata = await readCategoriesMetadata(
+      options.version.contentPath,
+    );
+    const processedSidebars = await processSidebars(
+      normalizedSidebars,
+      categoriesMetadata,
+      options,
+    );
+    return postProcessSidebars(processedSidebars, options);
+  } catch (err) {
+    logger.error`Sidebars file at path=${
+      sidebarFilePath as string
+    } failed to be loaded.`;
+    throw err;
+  }
 }

package/src/sidebars/postProcessor.ts

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

package/src/sidebars/processor.ts

@@ -31,6 +31,7 @@ function toSidebarItemsGeneratorDoc(
   return _.pick(doc, [
     'id',
     'unversionedId',
+    'title',
     'frontMatter',
     'source',
     'sourceDirName',
@@ -48,16 +49,10 @@ function toSidebarItemsGeneratorVersion(
 // post-processing checks
 async function processSidebar(
   unprocessedSidebar: NormalizedSidebar,
-  categoriesMetadata: Record<string, CategoryMetadataFile>,
+  categoriesMetadata: {[filePath: string]: CategoryMetadataFile},
   params: SidebarProcessorParams,
 ): Promise<ProcessedSidebar> {
-  const {
-    sidebarItemsGenerator,
-    numberPrefixParser,
-    docs,
-    version,
-    sidebarOptions,
-  } = params;
+  const {sidebarItemsGenerator, numberPrefixParser, docs, version} = params;
 
   // Just a minor lazy transformation optimization
   const getSidebarItemsGeneratorDocsAndVersion = _.memoize(() => ({
@@ -74,7 +69,6 @@ async function processSidebar(
       defaultSidebarItemsGenerator: DefaultSidebarItemsGenerator,
       isCategoryIndex,
       ...getSidebarItemsGeneratorDocsAndVersion(),
-      options: sidebarOptions,
       categoriesMetadata,
     });
     // Process again... weird but sidebar item generated might generate some
@@ -113,7 +107,7 @@ async function processSidebar(
 
 export async function processSidebars(
   unprocessedSidebars: NormalizedSidebars,
-  categoriesMetadata: Record<string, CategoryMetadataFile>,
+  categoriesMetadata: {[filePath: string]: CategoryMetadataFile},
   params: SidebarProcessorParams,
 ): Promise<ProcessedSidebars> {
   const processedSidebars = await combinePromises(

package/src/sidebars/types.ts

@@ -15,11 +15,11 @@ import type {
 import type {Slugger} from '@docusaurus/utils';
 
 // Makes all properties visible when hovering over the type
-type Expand<T extends Record<string, unknown>> = {[P in keyof T]: T[P]};
+type Expand<T extends {[x: string]: unknown}> = {[P in keyof T]: T[P]};
 
 export type SidebarItemBase = {
   className?: string;
-  customProps?: Record<string, unknown>;
+  customProps?: {[key: string]: unknown};
 };
 
 export type SidebarItemDoc = SidebarItemBase & {
@@ -216,6 +216,7 @@ export type CategoryMetadataFile = {
   collapsible?: boolean;
   className?: string;
   link?: SidebarItemCategoryLinkConfig | null;
+  customProps?: {[key: string]: unknown};
 
   // TODO should we allow "items" here? how would this work? would an
   // "autogenerated" type be allowed?
@@ -230,6 +231,7 @@ export type SidebarItemsGeneratorDoc = Pick<
   DocMetadataBase,
   | 'id'
   | 'unversionedId'
+  | 'title'
   | 'frontMatter'
   | 'source'
   | 'sourceDirName'
@@ -246,8 +248,7 @@ export type SidebarItemsGeneratorArgs = {
   docs: SidebarItemsGeneratorDoc[];
   numberPrefixParser: NumberPrefixParser;
   isCategoryIndex: CategoryIndexMatcher;
-  categoriesMetadata: Record<string, CategoryMetadataFile>;
-  options: SidebarOptions;
+  categoriesMetadata: {[filePath: string]: CategoryMetadataFile};
 };
 export type SidebarItemsGenerator = (
   generatorArgs: SidebarItemsGeneratorArgs,