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

package/src/numberPrefix.ts

@@ -5,43 +5,36 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import {NumberPrefixParser} from './types';
+import type {NumberPrefixParser} from '@docusaurus/plugin-content-docs';
 
 // Best-effort to avoid parsing some patterns as number prefix
-const IgnoredPrefixPatterns = (function () {
-  // 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 his own NumberPrefixParser if he 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

@@ -4,7 +4,8 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import {PluginOptions} from './types';
+
+import type {PluginOptions, Options} from '@docusaurus/plugin-content-docs';
 import {
   Joi,
   RemarkPluginsSchema,
@@ -12,10 +13,12 @@ import {
   AdmonitionsSchema,
   URISchema,
 } from '@docusaurus/utils-validation';
-import {OptionValidationContext, ValidationResult} from '@docusaurus/types';
-import chalk from 'chalk';
+import {GlobExcludeDefault} from '@docusaurus/utils';
+
+import type {OptionValidationContext} from '@docusaurus/types';
+import logger from '@docusaurus/logger';
 import admonitions from 'remark-admonitions';
-import {DefaultSidebarItemsGenerator} from './sidebarItemsGenerator';
+import {DefaultSidebarItemsGenerator} from './sidebars/generator';
 import {
   DefaultNumberPrefixParser,
   DisabledNumberPrefixParser,
@@ -24,12 +27,16 @@ import {
 export const DEFAULT_OPTIONS: Omit<PluginOptions, 'id' | 'sidebarPath'> = {
   path: 'docs', // Path to data on filesystem, relative to site dir.
   routeBasePath: 'docs', // URL Route.
-  homePageId: undefined, // TODO remove soon, deprecated
+  tagsBasePath: 'tags', // URL Tags Route.
   include: ['**/*.{md,mdx}'], // Extensions to include.
+  exclude: GlobExcludeDefault,
   sidebarItemsGenerator: DefaultSidebarItemsGenerator,
   numberPrefixParser: DefaultNumberPrefixParser,
   docLayoutComponent: '@theme/DocPage',
   docItemComponent: '@theme/DocItem',
+  docTagDocListComponent: '@theme/DocTagDocListPage',
+  docTagsListComponent: '@theme/DocTagsListPage',
+  docCategoryGeneratedIndexComponent: '@theme/DocCategoryGeneratedIndexPage',
   remarkPlugins: [],
   rehypePlugins: [],
   beforeDefaultRemarkPlugins: [],
@@ -37,25 +44,30 @@ export const DEFAULT_OPTIONS: Omit<PluginOptions, 'id' | 'sidebarPath'> = {
   showLastUpdateTime: false,
   showLastUpdateAuthor: false,
   admonitions: {},
-  excludeNextVersionDocs: false,
   includeCurrentVersion: true,
   disableVersioning: false,
   lastVersion: undefined,
   versions: {},
   editCurrentVersion: false,
   editLocalizedFiles: false,
+  sidebarCollapsible: true,
+  sidebarCollapsed: true,
+  breadcrumbs: true,
 };
 
 const VersionOptionsSchema = Joi.object({
   path: Joi.string().allow('').optional(),
   label: Joi.string().optional(),
+  banner: Joi.string().equal('none', 'unreleased', 'unmaintained').optional(),
+  badge: Joi.boolean().optional(),
+  className: Joi.string().optional(),
 });
 
 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),
@@ -64,8 +76,15 @@ export const OptionsSchema = Joi.object({
     // '' not allowed, see https://github.com/facebook/docusaurus/issues/3374
     // .allow('') ""
     .default(DEFAULT_OPTIONS.routeBasePath),
-  homePageId: Joi.string().optional(),
+  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',
+  }),
+
   include: Joi.array().items(Joi.string()).default(DEFAULT_OPTIONS.include),
+  exclude: Joi.array().items(Joi.string()).default(DEFAULT_OPTIONS.exclude),
   sidebarPath: Joi.alternatives().try(
     Joi.boolean().invalid(true),
     Joi.string(),
@@ -73,6 +92,8 @@ export const OptionsSchema = Joi.object({
   sidebarItemsGenerator: Joi.function().default(
     () => DEFAULT_OPTIONS.sidebarItemsGenerator,
   ),
+  sidebarCollapsible: Joi.boolean().default(DEFAULT_OPTIONS.sidebarCollapsible),
+  sidebarCollapsed: Joi.boolean().default(DEFAULT_OPTIONS.sidebarCollapsed),
   numberPrefixParser: Joi.alternatives()
     .try(
       Joi.function(),
@@ -86,6 +107,15 @@ export const OptionsSchema = Joi.object({
     .default(() => DEFAULT_OPTIONS.numberPrefixParser),
   docLayoutComponent: Joi.string().default(DEFAULT_OPTIONS.docLayoutComponent),
   docItemComponent: Joi.string().default(DEFAULT_OPTIONS.docItemComponent),
+  docTagsListComponent: Joi.string().default(
+    DEFAULT_OPTIONS.docTagsListComponent,
+  ),
+  docTagDocListComponent: Joi.string().default(
+    DEFAULT_OPTIONS.docTagDocListComponent,
+  ),
+  docCategoryGeneratedIndexComponent: Joi.string().default(
+    DEFAULT_OPTIONS.docCategoryGeneratedIndexComponent,
+  ),
   remarkPlugins: RemarkPluginsSchema.default(DEFAULT_OPTIONS.remarkPlugins),
   rehypePlugins: RehypePluginsSchema.default(DEFAULT_OPTIONS.rehypePlugins),
   beforeDefaultRemarkPlugins: RemarkPluginsSchema.default(
@@ -101,9 +131,6 @@ export const OptionsSchema = Joi.object({
   showLastUpdateAuthor: Joi.bool().default(
     DEFAULT_OPTIONS.showLastUpdateAuthor,
   ),
-  excludeNextVersionDocs: Joi.bool().default(
-    DEFAULT_OPTIONS.excludeNextVersionDocs,
-  ),
   includeCurrentVersion: Joi.bool().default(
     DEFAULT_OPTIONS.includeCurrentVersion,
   ),
@@ -111,34 +138,35 @@ 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({
   validate,
-  options,
-}: OptionValidationContext<PluginOptions>): ValidationResult<PluginOptions> {
-  // TODO remove homePageId before end of 2020
-  // "slug: /" is better because the home doc can be different across versions
-  if (options.homePageId) {
-    console.log(
-      chalk.red(
-        `The docs plugin option homePageId=${options.homePageId} is deprecated. To make a doc the "home", prefer frontmatter: "slug: /"`,
-      ),
-    );
-  }
+  options: userOptions,
+}: OptionValidationContext<Options, PluginOptions>): PluginOptions {
+  let options = userOptions;
 
-  if (typeof options.excludeNextVersionDocs !== 'undefined') {
-    console.log(
-      chalk.red(
-        `The docs plugin option excludeNextVersionDocs=${
-          options.excludeNextVersionDocs
-        } is deprecated. Use the includeCurrentVersion=${!options.excludeNextVersionDocs} option instead!"`,
-      ),
-    );
-    options.includeCurrentVersion = !options.excludeNextVersionDocs;
+  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
+    if (typeof options.sidebarCollapsed === 'undefined') {
+      options = {
+        ...options,
+        sidebarCollapsed: false,
+      };
+    }
+    if (options.sidebarCollapsed) {
+      logger.warn`The docs plugin config is inconsistent. It does not make sense to use code=${'sidebarCollapsible: false'} and code=${'sidebarCollapsed: true'} at the same time. code=${'sidebarCollapsed: true'} will be ignored.`;
+      options = {
+        ...options,
+        sidebarCollapsed: false,
+      };
+    }
   }
 
-  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

@@ -5,53 +5,178 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-/* eslint-disable camelcase */
+declare module '@docusaurus/plugin-content-docs' {
+  import type {RemarkAndRehypePluginOptions} from '@docusaurus/mdx-loader';
 
-declare module '@docusaurus/plugin-content-docs-types' {
-  export type PermalinkToSidebar = {
-    [permalink: string]: string;
+  export interface Assets {
+    image?: string;
+  }
+
+  export type NumberPrefixParser = (filename: string) => {
+    filename: string;
+    numberPrefix?: number;
+  };
+
+  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 = (
+    param: CategoryIndexMatcherParam,
+  ) => boolean;
+
+  export type EditUrlFunction = (editUrlParams: {
+    version: string;
+    versionDocsDirPath: string;
+    docPath: string;
+    permalink: string;
+    locale: string;
+  }) => string | undefined;
+
+  export type MetadataOptions = {
+    routeBasePath: string;
+    editUrl?: string | EditUrlFunction;
+    editCurrentVersion: boolean;
+    editLocalizedFiles: boolean;
+    showLastUpdateTime?: boolean;
+    showLastUpdateAuthor?: boolean;
+    numberPrefixParser: NumberPrefixParser;
+    breadcrumbs: boolean;
   };
 
+  export type PathOptions = {
+    path: string;
+    sidebarPath?: string | false | undefined;
+  };
+
+  // TODO support custom version banner?
+  // {type: "error", content: "html content"}
+  export type VersionBanner = 'unreleased' | 'unmaintained';
+  export type VersionOptions = {
+    path?: string;
+    label?: string;
+    banner?: 'none' | VersionBanner;
+    badge?: boolean;
+    className?: string;
+  };
+  export type VersionsOptions = {
+    lastVersion?: string;
+    versions: {[versionName: string]: VersionOptions};
+    onlyIncludeVersions?: string[];
+  };
+  export type SidebarOptions = {
+    sidebarCollapsible: boolean;
+    sidebarCollapsed: boolean;
+  };
+
+  export type PluginOptions = MetadataOptions &
+    PathOptions &
+    VersionsOptions &
+    RemarkAndRehypePluginOptions &
+    SidebarOptions & {
+      id: string;
+      include: string[];
+      exclude: string[];
+      docLayoutComponent: string;
+      docItemComponent: string;
+      docTagDocListComponent: string;
+      docTagsListComponent: string;
+      docCategoryGeneratedIndexComponent: string;
+      admonitions: {[key: string]: unknown};
+      disableVersioning: boolean;
+      includeCurrentVersion: boolean;
+      sidebarItemsGenerator: import('./sidebars/types').SidebarItemsGeneratorOption;
+      tagsBasePath: string;
+    };
+  export type Options = Partial<PluginOptions>;
+  export type SidebarsConfig = import('./sidebars/types').SidebarsConfig;
+
+  export type PropNavigationLink = {
+    readonly title: string;
+    readonly permalink: string;
+  };
+  export type PropNavigation = {
+    readonly previous?: PropNavigationLink;
+    readonly next?: PropNavigationLink;
+  };
+
+  export type PropVersionDoc = import('./sidebars/types').PropVersionDoc;
+  export type PropVersionDocs = import('./sidebars/types').PropVersionDocs;
+
   export type PropVersionMetadata = {
     pluginId: string;
     version: string;
     label: string;
+    banner: VersionBanner | null;
+    badge: boolean;
+    className: string;
     isLast: boolean;
     docsSidebars: PropSidebars;
-    permalinkToSidebar: PermalinkToSidebar;
+    docs: PropVersionDocs;
   };
 
-  type PropsSidebarItemBase = {
-    customProps?: Record<string, unknown>;
+  export type PropCategoryGeneratedIndex = {
+    title: string;
+    description?: string;
+    image?: string;
+    keywords?: string | readonly string[];
+    slug: string;
+    permalink: string;
+    navigation: PropNavigation;
   };
 
-  export type PropSidebarItemLink = PropsSidebarItemBase & {
-    type: 'link';
-    href: string;
-    label: string;
-  };
+  export type PropSidebarItemLink =
+    import('./sidebars/types').PropSidebarItemLink;
+  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;
 
-  export type PropSidebarItemCategory = PropsSidebarItemBase & {
-    type: 'category';
-    label: string;
-    items: PropSidebarItem[];
-    collapsed?: boolean;
+  export type PropTagDocListDoc = {
+    id: string;
+    title: string;
+    description: string;
+    permalink: string;
+  };
+  export type PropTagDocList = {
+    allTagsPath: string;
+    name: string; // normalized name/label of the tag
+    permalink: string; // pathname of the tag
+    docs: PropTagDocListDoc[];
   };
 
-  export type PropSidebarItem = PropSidebarItemLink | PropSidebarItemCategory;
-
-  export type PropSidebars = {
-    [sidebarId: string]: PropSidebarItem[];
+  export type PropTagsListPage = {
+    tags: {
+      name: string;
+      permalink: string;
+      count: number;
+    }[];
   };
 }
 
 declare module '@theme/DocItem' {
   import type {TOCItem} from '@docusaurus/types';
+  import type {
+    PropNavigationLink,
+    PropVersionMetadata,
+    Assets,
+  } from '@docusaurus/plugin-content-docs';
 
   export type DocumentRoute = {
     readonly component: () => JSX.Element;
     readonly exact: boolean;
     readonly path: string;
+    readonly sidebar?: string;
   };
 
   export type FrontMatter = {
@@ -61,9 +186,12 @@ declare module '@theme/DocItem' {
     readonly keywords?: readonly string[];
     readonly hide_title?: boolean;
     readonly hide_table_of_contents?: boolean;
+    readonly toc_min_heading_level?: number;
+    readonly toc_max_heading_level?: number;
   };
 
   export type Metadata = {
+    readonly unversionedId?: string;
     readonly description?: string;
     readonly title?: string;
     readonly permalink?: string;
@@ -72,29 +200,67 @@ declare module '@theme/DocItem' {
     readonly formattedLastUpdatedAt?: string;
     readonly lastUpdatedBy?: string;
     readonly version?: string;
-    readonly previous?: {readonly permalink: string; readonly title: string};
-    readonly next?: {readonly permalink: string; readonly title: string};
+    readonly previous?: PropNavigationLink;
+    readonly next?: PropNavigationLink;
+    readonly tags: readonly {
+      readonly label: string;
+      readonly permalink: string;
+    }[];
   };
 
-  export type Props = {
+  export interface Props {
     readonly route: DocumentRoute;
+    readonly versionMetadata: PropVersionMetadata;
     readonly content: {
       readonly frontMatter: FrontMatter;
       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;
+  export default function DocItem(props: Props): JSX.Element;
+}
+
+declare module '@theme/DocCategoryGeneratedIndexPage' {
+  import type {PropCategoryGeneratedIndex} from '@docusaurus/plugin-content-docs';
+
+  export interface Props {
+    readonly categoryGeneratedIndex: PropCategoryGeneratedIndex;
+  }
+
+  export default function DocCategoryGeneratedIndexPage(
+    props: Props,
+  ): JSX.Element;
+}
+
+declare module '@theme/DocTagsListPage' {
+  import type {PropTagsListPage} from '@docusaurus/plugin-content-docs';
+
+  export interface Props extends PropTagsListPage {}
+  export default function DocTagsListPage(props: Props): JSX.Element;
+}
+
+declare module '@theme/DocTagDocListPage' {
+  import type {PropTagDocList} from '@docusaurus/plugin-content-docs';
+
+  export interface Props {
+    readonly tag: PropTagDocList;
+  }
+  export default function DocTagDocListPage(props: Props): JSX.Element;
+}
+
+declare module '@theme/DocBreadcrumbs' {
+  export default function DocBreadcrumbs(): JSX.Element;
 }
 
 declare module '@theme/DocPage' {
-  import type {PropVersionMetadata} from '@docusaurus/plugin-content-docs-types';
+  import type {PropVersionMetadata} from '@docusaurus/plugin-content-docs';
   import type {DocumentRoute} from '@theme/DocItem';
 
-  export type Props = {
+  export interface Props {
     readonly location: {readonly pathname: string};
     readonly versionMetadata: PropVersionMetadata;
     readonly route: {
@@ -102,20 +268,77 @@ declare module '@theme/DocPage' {
       readonly component: () => JSX.Element;
       readonly routes: DocumentRoute[];
     };
-  };
+  }
 
-  const DocPage: (props: Props) => JSX.Element;
-  export default DocPage;
+  export default function DocPage(props: Props): JSX.Element;
 }
 
-declare module '@theme/Seo' {
-  export type Props = {
-    readonly title?: string;
-    readonly description?: string;
-    readonly keywords?: readonly string[] | string;
-    readonly image?: string;
+// TODO until TS supports exports field... hope it's in 4.6
+declare module '@docusaurus/plugin-content-docs/client' {
+  export type ActivePlugin = {
+    pluginId: string;
+    pluginData: GlobalPluginData;
+  };
+  export type ActiveDocContext = {
+    activeVersion?: GlobalVersion;
+    activeDoc?: GlobalDoc;
+    alternateDocVersions: {[versionName: string]: GlobalDoc};
+  };
+  export type GlobalDoc = {
+    id: string;
+    path: string;
+    sidebar: string | undefined;
+  };
+
+  export type GlobalVersion = {
+    name: string;
+    label: string;
+    isLast: boolean;
+    path: string;
+    mainDocId: string; // home doc (if docs homepage configured), or first doc
+    docs: GlobalDoc[];
+    sidebars?: {[sidebarId: string]: GlobalSidebar};
+  };
+
+  export type GlobalSidebarLink = {
+    label: string;
+    path: string;
+  };
+
+  export type GlobalSidebar = {
+    link?: GlobalSidebarLink;
+    // ... 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 exist)
+    latestDocSuggestion?: GlobalDoc;
   };
+  export type GetActivePluginOptions = {failfast?: boolean}; // use fail-fast option if you know for sure one plugin instance is active
 
-  const Seo: (props: Props) => JSX.Element;
-  export default Seo;
+  export const useAllDocsData: () => {[pluginId: string]: GlobalPluginData};
+  export const useDocsData: (pluginId?: string) => GlobalPluginData;
+  export const useActivePlugin: (
+    options?: GetActivePluginOptions,
+  ) => ActivePlugin | undefined;
+  export const useActivePluginAndVersion: (
+    options?: GetActivePluginOptions,
+  ) =>
+    | {activePlugin: ActivePlugin; activeVersion: GlobalVersion | undefined}
+    | undefined;
+  export const useVersions: (pluginId?: string) => GlobalVersion[];
+  export const useLatestVersion: (pluginId?: string) => GlobalVersion;
+  export const useActiveVersion: (
+    pluginId?: string,
+  ) => GlobalVersion | undefined;
+  export const useActiveDocContext: (pluginId?: string) => ActiveDocContext;
+  export const useDocVersionSuggestions: (
+    pluginId?: string,
+  ) => DocVersionSuggestions;
 }