@docusaurus/plugin-content-docs 2.0.0-beta.8bda3b2db → 2.0.0-beta.9

package/src/options.ts

@@ -12,10 +12,12 @@ import {
   AdmonitionsSchema,
   URISchema,
 } from '@docusaurus/utils-validation';
+import {GlobExcludeDefault} from '@docusaurus/utils';
+
 import {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 +26,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.
+  tagsBasePath: 'tags', // URL Tags Route.
   homePageId: undefined, // TODO remove soon, deprecated
   include: ['**/*.{md,mdx}'], // Extensions to include.
+  exclude: GlobExcludeDefault,
   sidebarItemsGenerator: DefaultSidebarItemsGenerator,
   numberPrefixParser: DefaultNumberPrefixParser,
   docLayoutComponent: '@theme/DocPage',
   docItemComponent: '@theme/DocItem',
+  docTagDocListComponent: '@theme/DocTagDocListPage',
+  docTagsListComponent: '@theme/DocTagsListPage',
   remarkPlugins: [],
   rehypePlugins: [],
   beforeDefaultRemarkPlugins: [],
@@ -37,18 +43,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 +74,10 @@ export const OptionsSchema = Joi.object({
     // '' not allowed, see https://github.com/facebook/docusaurus/issues/3374
     // .allow('') ""
     .default(DEFAULT_OPTIONS.routeBasePath),
+  tagsBasePath: Joi.string().default(DEFAULT_OPTIONS.tagsBasePath),
   homePageId: Joi.string().optional(),
   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 +85,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 +100,12 @@ 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,
+  ),
   remarkPlugins: RemarkPluginsSchema.default(DEFAULT_OPTIONS.remarkPlugins),
   rehypePlugins: RehypePluginsSchema.default(DEFAULT_OPTIONS.rehypePlugins),
   beforeDefaultRemarkPlugins: RemarkPluginsSchema.default(
@@ -101,9 +121,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,8 +132,32 @@ export const OptionsSchema = Joi.object({
 
 export function validateOptions({
   validate,
-  options,
+  options: userOptions,
 }: OptionValidationContext<PluginOptions>): ValidationResult<PluginOptions> {
+  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
+    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,
+      };
+    }
+  }
+
   // TODO remove homePageId before end of 2020
   // "slug: /" is better because the home doc can be different across versions
   if (options.homePageId) {
@@ -127,17 +168,6 @@ export function validateOptions({
     );
   }
 
-  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;
-  }
-
   const normalizedOptions = validate(OptionsSchema, options);
 
   if (normalizedOptions.admonitions) {

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

@@ -5,58 +5,68 @@
  * 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;
+}
 
+// TODO public api surface types should rather be exposed as "@docusaurus/plugin-content-docs"
 declare module '@docusaurus/plugin-content-docs-types' {
-  export type PermalinkToSidebar = {
-    [permalink: string]: string;
-  };
+  export type VersionBanner = import('./types').VersionBanner;
+  type GlobalDataVersion = import('./types').GlobalVersion;
+  type GlobalDataDoc = import('./types').GlobalDoc;
+  type VersionTag = import('./types').VersionTag;
+
+  export type {GlobalDataVersion, GlobalDataDoc};
 
   export type PropVersionMetadata = {
     pluginId: string;
     version: string;
     label: string;
+    banner: VersionBanner | null;
+    badge: boolean;
+    className: string;
     isLast: boolean;
     docsSidebars: PropSidebars;
-    permalinkToSidebar: PermalinkToSidebar;
   };
 
-  type PropsSidebarItemBase = {
-    customProps?: Record<string, unknown>;
+  export type PropSidebarItemLink = import('./sidebars/types').SidebarItemLink;
+  export type PropSidebarItemCategory =
+    import('./sidebars/types').PropSidebarItemCategory;
+  export type PropSidebarItem = import('./sidebars/types').PropSidebarItem;
+  export type PropSidebars = import('./sidebars/types').PropSidebars;
+
+  export type PropTagDocListDoc = {
+    id: string;
+    title: string;
+    description: string;
+    permalink: string;
   };
-
-  export type PropSidebarItemLink = PropsSidebarItemBase & {
-    type: 'link';
-    href: string;
-    label: string;
+  export type PropTagDocList = {
+    allTagsPath: string;
+    name: string; // normalized name/label of the tag
+    permalink: string; // pathname of the tag
+    docs: PropTagDocListDoc[];
   };
 
-  export type PropSidebarItemCategory = PropsSidebarItemBase & {
-    type: 'category';
-    label: string;
-    items: PropSidebarItem[];
-    collapsed?: boolean;
-  };
-
-  export type PropSidebarItem = PropSidebarItemLink | PropSidebarItemCategory;
-
-  export type PropSidebars = {
-    [sidebarId: string]: PropSidebarItem[];
+  export type PropTagsListPage = {
+    tags: {
+      name: string;
+      permalink: string;
+      count: number;
+    }[];
   };
-
-  export type {
-    GlobalVersion as GlobalDataVersion,
-    GlobalDoc as GlobalDataDoc,
-  } from './types';
 }
 
 declare module '@theme/DocItem' {
   import type {TOCItem} from '@docusaurus/types';
+  import type {PropVersionMetadata} from '@docusaurus/plugin-content-docs-types';
 
   export type DocumentRoute = {
     readonly component: () => JSX.Element;
     readonly exact: boolean;
     readonly path: string;
+    readonly sidebar?: string;
   };
 
   export type FrontMatter = {
@@ -64,8 +74,12 @@ declare module '@theme/DocItem' {
     readonly title: string;
     readonly image?: string;
     readonly keywords?: readonly string[];
+    /* eslint-disable camelcase */
     readonly hide_title?: boolean;
     readonly hide_table_of_contents?: boolean;
+    readonly toc_min_heading_level?: number;
+    readonly toc_max_heading_level?: number;
+    /* eslint-enable camelcase */
   };
 
   export type Metadata = {
@@ -79,10 +93,15 @@ declare module '@theme/DocItem' {
     readonly version?: string;
     readonly previous?: {readonly permalink: string; readonly title: string};
     readonly next?: {readonly permalink: string; readonly title: string};
+    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 +109,50 @@ declare module '@theme/DocItem' {
       readonly contentTitle: string | undefined;
       (): JSX.Element;
     };
-  };
+  }
 
   const DocItem: (props: Props) => JSX.Element;
   export default DocItem;
 }
 
+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-types';
+
+  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-types';
+
+  export interface Props {
+    readonly tag: PropTagDocList;
+  }
+  export default function DocTagDocListPage(props: Props): JSX.Element;
+}
+
+declare module '@theme/DocVersionBanner' {
+  import type {PropVersionMetadata} from '@docusaurus/plugin-content-docs-types';
+
+  export interface Props {
+    readonly versionMetadata: PropVersionMetadata;
+  }
+
+  const DocVersionBanner: (props: Props) => JSX.Element;
+  export default DocVersionBanner;
+}
+
 declare module '@theme/DocPage' {
   import type {PropVersionMetadata} from '@docusaurus/plugin-content-docs-types';
   import type {DocumentRoute} from '@theme/DocItem';
 
-  export type Props = {
+  export interface Props {
     readonly location: {readonly pathname: string};
     readonly versionMetadata: PropVersionMetadata;
     readonly route: {
@@ -108,20 +160,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,18 +5,20 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import {
-  LoadedVersion,
+import {LoadedVersion, VersionTag, DocMetadata} from './types';
+import type {
   SidebarItemDoc,
   SidebarItemLink,
   SidebarItem,
-} from './types';
-import {
+} from './sidebars/types';
+import type {
   PropSidebars,
   PropVersionMetadata,
   PropSidebarItem,
+  PropTagDocList,
+  PropTagDocListDoc,
 } from '@docusaurus/plugin-content-docs-types';
-import {keyBy, mapValues} from 'lodash';
+import {compact, keyBy, mapValues} from 'lodash';
 
 export function toSidebarsProp(loadedVersion: LoadedVersion): PropSidebars {
   const docsById = keyBy(loadedVersion.docs, (doc) => doc.id);
@@ -43,6 +45,7 @@ Available document ids are:
       type: 'link',
       label: sidebarLabel || item.label || title,
       href: permalink,
+      className: item.className,
       customProps: item.customProps,
     };
   };
@@ -74,8 +77,41 @@ 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,
+  };
+}
+
+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,
   };
 }

package/src/{__tests__/__snapshots__/sidebars.test.ts.snap → sidebars/__tests__/__snapshots__/index.test.ts.snap}

@@ -1,10 +1,11 @@
 // Jest Snapshot v1, https://goo.gl/fbAQLP
 
-exports[`loadSidebars sidebars link 1`] = `
+exports[`loadUnprocessedSidebars sidebars link 1`] = `
 Object {
   "docs": Array [
     Object {
       "collapsed": true,
+      "collapsible": true,
       "items": Array [
         Object {
           "href": "https://github.com",
@@ -19,14 +20,16 @@ Object {
 }
 `;
 
-exports[`loadSidebars sidebars with category.collapsed property 1`] = `
+exports[`loadUnprocessedSidebars sidebars with category.collapsed property 1`] = `
 Object {
   "docs": Array [
     Object {
       "collapsed": true,
+      "collapsible": true,
       "items": Array [
         Object {
           "collapsed": false,
+          "collapsible": true,
           "items": Array [
             Object {
               "id": "doc1",
@@ -42,9 +45,11 @@ Object {
     },
     Object {
       "collapsed": true,
+      "collapsible": true,
       "items": Array [
         Object {
           "collapsed": false,
+          "collapsible": true,
           "items": Array [
             Object {
               "id": "doc2",
@@ -62,11 +67,12 @@ Object {
 }
 `;
 
-exports[`loadSidebars sidebars with category.collapsed property at first level 1`] = `
+exports[`loadUnprocessedSidebars sidebars with category.collapsed property at first level 1`] = `
 Object {
   "docs": Array [
     Object {
       "collapsed": false,
+      "collapsible": true,
       "items": Array [
         Object {
           "id": "doc1",
@@ -78,6 +84,7 @@ Object {
     },
     Object {
       "collapsed": false,
+      "collapsible": true,
       "items": Array [
         Object {
           "id": "doc2",
@@ -91,11 +98,12 @@ Object {
 }
 `;
 
-exports[`loadSidebars sidebars with deep level of category 1`] = `
+exports[`loadUnprocessedSidebars sidebars with deep level of category 1`] = `
 Object {
   "docs": Array [
     Object {
       "collapsed": true,
+      "collapsible": true,
       "items": Array [
         Object {
           "id": "a",
@@ -103,9 +111,11 @@ Object {
         },
         Object {
           "collapsed": true,
+          "collapsible": true,
           "items": Array [
             Object {
               "collapsed": true,
+              "collapsible": true,
               "items": Array [
                 Object {
                   "id": "c",
@@ -113,6 +123,7 @@ Object {
                 },
                 Object {
                   "collapsed": true,
+                  "collapsible": true,
                   "items": Array [
                     Object {
                       "id": "d",
@@ -120,6 +131,7 @@ Object {
                     },
                     Object {
                       "collapsed": true,
+                      "collapsible": true,
                       "items": Array [
                         Object {
                           "id": "e",
@@ -153,11 +165,12 @@ Object {
 }
 `;
 
-exports[`loadSidebars sidebars with first level not a category 1`] = `
+exports[`loadUnprocessedSidebars sidebars with first level not a category 1`] = `
 Object {
   "docs": Array [
     Object {
       "collapsed": true,
+      "collapsible": true,
       "items": Array [
         Object {
           "id": "greeting",
@@ -175,11 +188,12 @@ Object {
 }
 `;
 
-exports[`loadSidebars sidebars with known sidebar item type 1`] = `
+exports[`loadUnprocessedSidebars sidebars with known sidebar item type 1`] = `
 Object {
   "docs": Array [
     Object {
       "collapsed": true,
+      "collapsible": true,
       "items": Array [
         Object {
           "id": "foo/bar",
@@ -204,6 +218,7 @@ Object {
     },
     Object {
       "collapsed": true,
+      "collapsible": true,
       "items": Array [
         Object {
           "id": "hello",