@docusaurus/plugin-content-docs 2.0.0-beta.1 → 2.0.0-beta.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} from './types';
 import {
   Joi,
   RemarkPluginsSchema,
@@ -12,10 +13,15 @@ import {
   AdmonitionsSchema,
   URISchema,
 } from '@docusaurus/utils-validation';
-import {OptionValidationContext, ValidationResult} from '@docusaurus/types';
+import {GlobExcludeDefault} from '@docusaurus/utils';
+
+import type {
+  OptionValidationContext,
+  ValidationResult,
+} from '@docusaurus/types';
 import chalk from 'chalk';
 import admonitions from 'remark-admonitions';
-import {DefaultSidebarItemsGenerator} from './sidebarItemsGenerator';
+import {DefaultSidebarItemsGenerator} from './sidebars/generator';
 import {
   DefaultNumberPrefixParser,
   DisabledNumberPrefixParser,
@@ -24,12 +30,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,18 +47,22 @@ 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,
 };
 
 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()
@@ -64,8 +78,14 @@ 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),
+  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 +93,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 +108,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 +132,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,
   ),
@@ -115,27 +143,30 @@ export const OptionsSchema = Joi.object({
 
 export function validateOptions({
   validate,
-  options,
+  options: userOptions,
 }: 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: /"`,
-      ),
-    );
-  }
+  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) {
+      console.warn(
+        chalk.yellow(
+          'The docs plugin config is inconsistent. It does not make sense to use sidebarCollapsible=false and sidebarCollapsed=true at the same time. sidebarCollapsed=false will be ignored.',
+        ),
+      );
+      options = {
+        ...options,
+        sidebarCollapsed: false,
+      };
+    }
   }
 
   const normalizedOptions = validate(OptionsSchema, options);

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

@@ -5,58 +5,90 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-/* eslint-disable camelcase */
+declare module '@docusaurus/plugin-content-docs' {
+  export type Options = Partial<import('./types').PluginOptions>;
+  export type SidebarsConfig = import('./sidebars/types').SidebarsConfig;
+  export type VersionBanner = import('./types').VersionBanner;
+  type GlobalDataVersion = import('./types').GlobalVersion;
+  type GlobalDataDoc = import('./types').GlobalDoc;
+  type VersionTag = import('./types').VersionTag;
 
-declare module '@docusaurus/plugin-content-docs-types' {
-  export type PermalinkToSidebar = {
-    [permalink: string]: string;
+  export type {GlobalDataVersion, GlobalDataDoc};
+
+  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;
+    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 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 PropSidebarItem = PropSidebarItemLink | PropSidebarItemCategory;
-
-  export type PropSidebars = {
-    [sidebarId: string]: PropSidebarItem[];
+  export type PropTagDocList = {
+    allTagsPath: string;
+    name: string; // normalized name/label of the tag
+    permalink: string; // pathname of the tag
+    docs: PropTagDocListDoc[];
   };
 
-  export type {
-    GlobalVersion as GlobalDataVersion,
-    GlobalDoc as GlobalDataDoc,
-  } from './types';
+  export type PropTagsListPage = {
+    tags: {
+      name: string;
+      permalink: string;
+      count: number;
+    }[];
+  };
 }
 
 declare module '@theme/DocItem' {
   import type {TOCItem} from '@docusaurus/types';
+  import type {
+    PropNavigationLink,
+    PropVersionMetadata,
+  } from '@docusaurus/plugin-content-docs';
 
   export type DocumentRoute = {
     readonly component: () => JSX.Element;
     readonly exact: boolean;
     readonly path: string;
+    readonly sidebar?: string;
   };
 
   export type FrontMatter = {
@@ -66,6 +98,8 @@ 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 = {
@@ -77,12 +111,17 @@ 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;
@@ -90,17 +129,87 @@ declare module '@theme/DocItem' {
       readonly contentTitle: string | undefined;
       (): 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;
+}
+
+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/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';
+
+  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/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/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: {
@@ -108,20 +217,55 @@ declare module '@theme/DocPage' {
       readonly component: () => JSX.Element;
       readonly routes: DocumentRoute[];
     };
-  };
+  }
 
   const DocPage: (props: Props) => JSX.Element;
   export default DocPage;
 }
 
 declare module '@theme/Seo' {
-  export type Props = {
+  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;
 }
+
+declare module '@theme/hooks/useDocs' {
+  type GlobalPluginData = import('./types').GlobalPluginData;
+  type GlobalVersion = import('./types').GlobalVersion;
+  type ActivePlugin = import('./client/docsClientUtils').ActivePlugin;
+  type ActiveDocContext = import('./client/docsClientUtils').ActiveDocContext;
+  type DocVersionSuggestions =
+    import('./client/docsClientUtils').DocVersionSuggestions;
+  type GetActivePluginOptions =
+    import('./client/docsClientUtils').GetActivePluginOptions;
+
+  export type {GlobalPluginData, GlobalVersion};
+  export const useAllDocsData: () => Record<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;
+}

package/src/props.ts

@@ -5,26 +5,31 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import {
-  LoadedVersion,
+import type {LoadedVersion, VersionTag, DocMetadata} from './types';
+import type {
   SidebarItemDoc,
-  SidebarItemLink,
   SidebarItem,
-} from './types';
-import {
+  SidebarItemCategory,
+  SidebarItemCategoryLink,
+  PropVersionDocs,
+} from './sidebars/types';
+import type {
   PropSidebars,
   PropVersionMetadata,
   PropSidebarItem,
-} from '@docusaurus/plugin-content-docs-types';
-import {keyBy, mapValues} from 'lodash';
+  PropSidebarItemCategory,
+  PropTagDocList,
+  PropTagDocListDoc,
+  PropSidebarItemLink,
+} from '@docusaurus/plugin-content-docs';
+import {compact, keyBy, mapValues} from 'lodash';
+import {createDocsByIdIndex} from './docs';
 
 export function toSidebarsProp(loadedVersion: LoadedVersion): PropSidebars {
-  const docsById = keyBy(loadedVersion.docs, (doc) => doc.id);
+  const docsById = createDocsByIdIndex(loadedVersion.docs);
 
-  const convertDocLink = (item: SidebarItemDoc): SidebarItemLink => {
-    const docId = item.id;
+  function getDocById(docId: string): DocMetadata {
     const docMetadata = docsById[docId];
-
     if (!docMetadata) {
       throw new Error(
         `Invalid sidebars file. The document with id "${docId}" was used in the sidebar, but no document with this id could be found.
@@ -32,25 +37,49 @@ Available document ids are:
 - ${Object.keys(docsById).sort().join('\n- ')}`,
       );
     }
+    return docMetadata;
+  }
 
+  const convertDocLink = (item: SidebarItemDoc): PropSidebarItemLink => {
+    const docMetadata = getDocById(item.id);
     const {
       title,
       permalink,
       frontMatter: {sidebar_label: sidebarLabel},
     } = docMetadata;
-
     return {
       type: 'link',
       label: sidebarLabel || item.label || title,
       href: permalink,
+      className: item.className,
       customProps: item.customProps,
+      docId: docMetadata.unversionedId,
     };
   };
 
-  const normalizeItem = (item: SidebarItem): PropSidebarItem => {
+  function getCategoryLinkHref(
+    link: SidebarItemCategoryLink | undefined,
+  ): string | undefined {
+    switch (link?.type) {
+      case 'doc':
+        return getDocById(link.id).permalink;
+      case 'generated-index':
+        return link.permalink;
+      default:
+        return undefined;
+    }
+  }
+
+  function convertCategory(item: SidebarItemCategory): PropSidebarItemCategory {
+    const {link, ...rest} = item;
+    const href = getCategoryLinkHref(link);
+    return {...rest, items: item.items.map(normalizeItem), ...(href && {href})};
+  }
+
+  function normalizeItem(item: SidebarItem): PropSidebarItem {
     switch (item.type) {
       case 'category':
-        return {...item, items: item.items.map(normalizeItem)};
+        return convertCategory(item);
       case 'ref':
       case 'doc':
         return convertDocLink(item);
@@ -58,7 +87,7 @@ Available document ids are:
       default:
         return item;
     }
-  };
+  }
 
   // Transform the sidebar so that all sidebar item will be in the
   // form of 'link' or 'category' only.
@@ -66,6 +95,18 @@ Available document ids are:
   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,
+    }),
+  );
+}
+
 export function toVersionMetadataProp(
   pluginId: string,
   loadedVersion: LoadedVersion,
@@ -74,8 +115,42 @@ export function toVersionMetadataProp(
     pluginId,
     version: loadedVersion.versionName,
     label: loadedVersion.versionLabel,
+    banner: loadedVersion.versionBanner,
+    badge: loadedVersion.versionBadge,
+    className: loadedVersion.versionClassName,
     isLast: loadedVersion.isLast,
     docsSidebars: toSidebarsProp(loadedVersion),
-    permalinkToSidebar: loadedVersion.permalinkToSidebar,
+    docs: toVersionDocsProp(loadedVersion),
+  };
+}
+
+export function toTagDocListProp({
+  allTagsPath,
+  tag,
+  docs,
+}: {
+  allTagsPath: string;
+  tag: VersionTag;
+  docs: Pick<DocMetadata, 'id' | 'title' | 'description' | 'permalink'>[];
+}): PropTagDocList {
+  function toDocListProp(): PropTagDocListDoc[] {
+    const list = compact(
+      tag.docIds.map((id) => docs.find((doc) => doc.id === id)),
+    );
+    // Sort docs by title
+    list.sort((doc1, doc2) => doc1.title.localeCompare(doc2.title));
+    return list.map((doc) => ({
+      id: doc.id,
+      title: doc.title,
+      description: doc.description,
+      permalink: doc.permalink,
+    }));
+  }
+
+  return {
+    name: tag.name,
+    permalink: tag.permalink,
+    docs: toDocListProp(),
+    allTagsPath,
   };
 }