@docusaurus/plugin-content-docs 2.0.0-beta.12faed89d → 2.0.0-beta.14

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

@@ -5,51 +5,84 @@
  * 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' {
-  import type {VersionBanner} from './types';
+  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;
+    banner: VersionBanner | null;
+    badge: boolean;
+    className: string;
     isLast: boolean;
     docsSidebars: PropSidebars;
+    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;
@@ -65,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 = {
@@ -76,11 +111,15 @@ 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: {
@@ -90,28 +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' {
-  import type {PropVersionMetadata} from '@docusaurus/plugin-content-docs-types';
+  export interface Props {
+    readonly className?: string;
+  }
 
-  export type Props = {
-    readonly versionMetadata: PropVersionMetadata;
-  };
+  export default function DocVersionBanner(props: Props): JSX.Element;
+}
 
-  const DocVersionBanner: (props: Props) => JSX.Element;
-  export default DocVersionBanner;
+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: {
@@ -119,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,
@@ -75,7 +116,41 @@ export function toVersionMetadataProp(
     version: loadedVersion.versionName,
     label: loadedVersion.versionLabel,
     banner: loadedVersion.versionBanner,
+    badge: loadedVersion.versionBadge,
+    className: loadedVersion.versionClassName,
     isLast: loadedVersion.isLast,
     docsSidebars: toSidebarsProp(loadedVersion),
+    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,
   };
 }

package/src/routes.ts

@@ -0,0 +1,169 @@
+/**
+ * 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.
+ */
+
+import {PluginContentLoadedActions, RouteConfig} from '@docusaurus/types';
+import {docuHash, createSlugger} from '@docusaurus/utils';
+import {
+  CategoryGeneratedIndexMetadata,
+  DocMetadata,
+  LoadedVersion,
+} from './types';
+import type {PropCategoryGeneratedIndex} from '@docusaurus/plugin-content-docs';
+import {toVersionMetadataProp} from './props';
+import logger from '@docusaurus/logger';
+
+export async function createCategoryGeneratedIndexRoutes({
+  version,
+  actions,
+  docCategoryGeneratedIndexComponent,
+}: {
+  version: LoadedVersion;
+  actions: PluginContentLoadedActions;
+  docCategoryGeneratedIndexComponent: string;
+}): Promise<RouteConfig[]> {
+  const slugs = createSlugger();
+
+  async function createCategoryGeneratedIndexRoute(
+    categoryGeneratedIndex: CategoryGeneratedIndexMetadata,
+  ): Promise<RouteConfig> {
+    const {sidebar, title, description, slug, permalink, previous, next} =
+      categoryGeneratedIndex;
+
+    const propFileName = slugs.slug(
+      `${version.versionPath}-${categoryGeneratedIndex.sidebar}-category-${categoryGeneratedIndex.title}`,
+    );
+
+    const prop: PropCategoryGeneratedIndex = {
+      title,
+      description,
+      slug,
+      permalink,
+      navigation: {
+        previous,
+        next,
+      },
+    };
+
+    const propData = await actions.createData(
+      `${docuHash(`category/${propFileName}`)}.json`,
+      JSON.stringify(prop, null, 2),
+    );
+
+    return {
+      path: permalink,
+      component: docCategoryGeneratedIndexComponent,
+      exact: true,
+      modules: {
+        categoryGeneratedIndex: propData,
+      },
+      // Same as doc, this sidebar route attribute permits to associate this subpage to the given sidebar
+      ...(sidebar && {sidebar}),
+    };
+  }
+
+  return Promise.all(
+    version.categoryGeneratedIndices.map(createCategoryGeneratedIndexRoute),
+  );
+}
+
+export async function createDocRoutes({
+  docs,
+  actions,
+  docItemComponent,
+}: {
+  docs: DocMetadata[];
+  actions: PluginContentLoadedActions;
+  docItemComponent: string;
+}): Promise<RouteConfig[]> {
+  return Promise.all(
+    docs.map(async (metadataItem) => {
+      await actions.createData(
+        // Note that this created data path must be in sync with
+        // metadataPath provided to mdx-loader.
+        `${docuHash(metadataItem.source)}.json`,
+        JSON.stringify(metadataItem, null, 2),
+      );
+
+      const docRoute: RouteConfig = {
+        path: metadataItem.permalink,
+        component: docItemComponent,
+        exact: true,
+        modules: {
+          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)
+        ...(metadataItem.sidebar && {
+          sidebar: metadataItem.sidebar,
+        }),
+      };
+
+      return docRoute;
+    }),
+  );
+}
+
+export async function createVersionRoutes({
+  loadedVersion,
+  actions,
+  docItemComponent,
+  docLayoutComponent,
+  docCategoryGeneratedIndexComponent,
+  pluginId,
+  aliasedSource,
+}: {
+  loadedVersion: LoadedVersion;
+  actions: PluginContentLoadedActions;
+  docLayoutComponent: string;
+  docItemComponent: string;
+  docCategoryGeneratedIndexComponent: string;
+  pluginId: string;
+  aliasedSource: (str: string) => string;
+}): Promise<void> {
+  async function doCreateVersionRoutes(version: LoadedVersion): Promise<void> {
+    const versionMetadata = toVersionMetadataProp(pluginId, version);
+    const versionMetadataPropPath = await actions.createData(
+      `${docuHash(`version-${version.versionName}-metadata-prop`)}.json`,
+      JSON.stringify(versionMetadata, null, 2),
+    );
+
+    async function createVersionSubRoutes() {
+      const [docRoutes, sidebarsRoutes] = await Promise.all([
+        createDocRoutes({docs: version.docs, actions, docItemComponent}),
+        createCategoryGeneratedIndexRoutes({
+          version,
+          actions,
+          docCategoryGeneratedIndexComponent,
+        }),
+      ]);
+
+      const routes = [...docRoutes, ...sidebarsRoutes];
+      return routes.sort((a, b) => a.path.localeCompare(b.path));
+    }
+
+    actions.addRoute({
+      path: version.versionPath,
+      // allow matching /docs/* as well
+      exact: false,
+      // main docs component (DocPage)
+      component: docLayoutComponent,
+      // sub-routes for each doc
+      routes: await createVersionSubRoutes(),
+      modules: {
+        versionMetadata: aliasedSource(versionMetadataPropPath),
+      },
+      priority: version.routePriority,
+    });
+  }
+
+  try {
+    return await doCreateVersionRoutes(loadedVersion);
+  } catch (e) {
+    logger.error`Can't create version routes for version name=${loadedVersion.versionName}`;
+    throw e;
+  }
+}