feat(v2): Provide docs plugin typing (#3328)

packages/docusaurus-plugin-content-docs/package.json

@@ -3,6 +3,7 @@
   "version": "2.0.0-alpha.61",
   "description": "Docs content plugin for Docusaurus",
   "main": "lib/index.js",
+  "types": "src/plugin-content-docs.d.ts",
   "scripts": {
     "build": "tsc",
     "watch": "tsc --watch"

packages/docusaurus-plugin-content-docs/src/index.ts

@@ -22,7 +22,6 @@ import {
   PluginOptions,
   LoadedContent,
   SourceToPermalink,
-  PermalinkToSidebar,
   DocMetadataBase,
   DocMetadata,
   GlobalPluginData,
@@ -32,6 +31,7 @@ import {
   DocFile,
   DocsMarkdownOption,
 } from './types';
+import {PermalinkToSidebar} from '@docusaurus/plugin-content-docs-types';
 import {RuleSetRule} from 'webpack';
 import {cliDocsVersionCommand} from './cli';
 import {VERSIONS_JSON_FILE} from './constants';

packages/docusaurus-plugin-content-docs/src/plugin-content-docs.d.ts

@@ -0,0 +1,101 @@
+/**
+ * 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.
+ */
+
+/* eslint-disable camelcase */
+
+declare module '@docusaurus/plugin-content-docs-types' {
+  export type VersionName = string;
+
+  export type PermalinkToSidebar = {
+    [permalink: string]: string;
+  };
+
+  export type PropVersionMetadata = {
+    version: VersionName;
+    docsSidebars: PropSidebars;
+    permalinkToSidebar: PermalinkToSidebar;
+  };
+
+  export type PropSidebarItemLink = {
+    type: 'link';
+    href: string;
+    label: string;
+  };
+
+  export type PropSidebarItemCategory = {
+    type: 'category';
+    label: string;
+    items: PropSidebarItem[];
+    collapsed?: boolean;
+  };
+
+  export type PropSidebarItem = PropSidebarItemLink | PropSidebarItemCategory;
+
+  export type PropSidebars = {
+    [sidebarId: string]: PropSidebarItem[];
+  };
+}
+
+declare module '@theme/DocItem' {
+  import type {MarkdownRightTableOfContents} from '@docusaurus/types';
+
+  export type DocumentRoute = {
+    readonly component: () => JSX.Element;
+    readonly exact: boolean;
+    readonly path: string;
+  };
+
+  export type FrontMatter = {
+    readonly id: string;
+    readonly title: string;
+    readonly image?: string;
+    readonly keywords?: readonly string[];
+    readonly hide_title?: boolean;
+    readonly hide_table_of_contents?: boolean;
+  };
+
+  export type Metadata = {
+    readonly description?: string;
+    readonly title?: string;
+    readonly permalink?: string;
+    readonly editUrl?: string;
+    readonly lastUpdatedAt?: number;
+    readonly lastUpdatedBy?: string;
+    readonly version?: string;
+  };
+
+  export type Props = {
+    readonly route: DocumentRoute;
+    readonly content: {
+      readonly frontMatter: FrontMatter;
+      readonly metadata: Metadata;
+      readonly rightToc: MarkdownRightTableOfContents;
+      (): JSX.Element;
+    };
+  };
+
+  const DocItem: (props: Props) => JSX.Element;
+  export default DocItem;
+}
+
+declare module '@theme/DocPage' {
+  import type {PropVersionMetadata} from '@docusaurus/plugin-content-docs-types';
+  import type {DocumentRoute} from '@theme/DocItem';
+
+  export type Props = {
+    readonly location: {readonly pathname: string};
+    readonly versionMetadata: PropVersionMetadata;
+    readonly route: {
+      readonly path: string;
+      readonly component: () => JSX.Element;
+      readonly routes: readonly DocumentRoute[];
+    };
+  };
+
+  const DocPage: (props: Props) => JSX.Element;
+  export default DocPage;
+}

packages/docusaurus-plugin-content-docs/src/props.ts

@@ -7,13 +7,15 @@
 
 import {
   LoadedVersion,
-  PropSidebars,
   SidebarItemDoc,
   SidebarItemLink,
-  PropVersionMetadata,
   SidebarItem,
-  PropSidebarItem,
 } from './types';
+import {
+  PropSidebars,
+  PropVersionMetadata,
+  PropSidebarItem,
+} from '@docusaurus/plugin-content-docs-types';
 import {keyBy, mapValues} from 'lodash';
 
 export function toSidebarsProp(loadedVersion: LoadedVersion): PropSidebars {

packages/docusaurus-plugin-content-docs/src/slug.ts

@@ -20,7 +20,7 @@ export default function getSlug({
   baseID: string;
   frontmatterSlug?: string;
   dirName: string;
-}) {
+}): string {
   const baseSlug: string = frontmatterSlug || baseID;
   let slug: string;
   if (baseSlug.startsWith('/')) {

packages/docusaurus-plugin-content-docs/src/types.ts

@@ -119,11 +119,6 @@ export type DocMetadata = DocMetadataBase & {
 export type SourceToPermalink = {
   [source: string]: string;
 };
-
-export type PermalinkToSidebar = {
-  [permalink: string]: string;
-};
-
 export type LoadedVersion = VersionMetadata & {
   versionPath: string;
   mainDocId: string;
@@ -155,27 +150,6 @@ export type GlobalPluginData = {
   versions: GlobalVersion[];
 };
 
-export type PropVersionMetadata = {
-  version: VersionName;
-  docsSidebars: PropSidebars;
-  permalinkToSidebar: PermalinkToSidebar;
-};
-
-export type PropSidebarItemLink = SidebarItemLink; // same
-
-export type PropSidebarItemCategory = {
-  type: 'category';
-  label: string;
-  items: PropSidebarItem[];
-  collapsed?: boolean;
-};
-
-export type PropSidebarItem = PropSidebarItemLink | PropSidebarItemCategory;
-
-export type PropSidebars = {
-  [sidebarId: string]: PropSidebarItem[];
-};
-
 export type BrokenMarkdownLink = {
   filePath: string;
   version: VersionMetadata;

packages/docusaurus-theme-classic/package.json

@@ -38,6 +38,7 @@
   "peerDependencies": {
     "@docusaurus/core": "^2.0.0",
     "@docusaurus/plugin-content-blog": "^2.0.0-alpha.61",
+    "@docusaurus/plugin-content-docs": "^2.0.0-alpha.61",
     "react": "^16.8.4",
     "react-dom": "^16.8.4"
   },

packages/docusaurus-theme-classic/src/theme/DocItem/index.tsx

@@ -12,12 +12,13 @@ import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
 import useBaseUrl from '@docusaurus/useBaseUrl';
 import DocPaginator from '@theme/DocPaginator';
 import DocVersionSuggestions from '@theme/DocVersionSuggestions';
+import type {Props} from '@theme/DocItem';
 import TOC from '@theme/TOC';
 
 import clsx from 'clsx';
 import styles from './styles.module.css';
 
-function DocItem(props): JSX.Element {
+function DocItem(props: Props): JSX.Element {
   const {siteConfig = {}} = useDocusaurusContext();
   const {url: siteUrl, title: siteTitle} = siteConfig;
   const {content: DocContent} = props;

packages/docusaurus-theme-classic/src/theme/DocPage/index.tsx

@@ -5,24 +5,33 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import React from 'react';
+import React, {ReactNode} from 'react';
 import {MDXProvider} from '@mdx-js/react';
 
 import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
 import renderRoutes from '@docusaurus/renderRoutes';
+import type {PropVersionMetadata} from '@docusaurus/plugin-content-docs-types';
 import Layout from '@theme/Layout';
 import DocSidebar from '@theme/DocSidebar';
 import MDXComponents from '@theme/MDXComponents';
 import NotFound from '@theme/NotFound';
+import type {DocumentRoute} from '@theme/DocItem';
+import type {Props} from '@theme/DocPage';
 import {matchPath} from '@docusaurus/router';
 
 import styles from './styles.module.css';
 
+type DocPageContentProps = {
+  readonly currentDocRoute: DocumentRoute;
+  readonly versionMetadata: PropVersionMetadata;
+  readonly children: ReactNode;
+};
+
 function DocPageContent({
   currentDocRoute,
   versionMetadata,
   children,
-}): JSX.Element {
+}: DocPageContentProps): JSX.Element {
   const {siteConfig, isClient} = useDocusaurusContext();
   const {permalinkToSidebar, docsSidebars, version} = versionMetadata;
   const sidebarName = permalinkToSidebar[currentDocRoute.path];
@@ -49,7 +58,7 @@ function DocPageContent({
   );
 }
 
-function DocPage(props) {
+function DocPage(props: Props): JSX.Element {
   const {
     route: {routes: docRoutes},
     versionMetadata,

packages/docusaurus-theme-classic/src/types.d.ts

@@ -8,3 +8,4 @@
 /* eslint-disable spaced-comment */
 /// <reference types="@docusaurus/module-type-aliases" />
 /// <reference types="@docusaurus/plugin-content-blog" />
+/// <reference types="@docusaurus/plugin-content-docs" />