@docusaurus/plugin-content-docs 0.0.0-4853 → 0.0.0-4855

package/lib/client/docsClientUtils.d.ts

@@ -10,6 +10,6 @@ export declare function getActivePlugin(allPluginData: {
     [pluginId: string]: GlobalPluginData;
 }, pathname: string, options?: UseDataOptions): ActivePlugin | undefined;
 export declare const getLatestVersion: (data: GlobalPluginData) => GlobalVersion;
-export declare const getActiveVersion: (data: GlobalPluginData, pathname: string) => GlobalVersion | undefined;
-export declare const getActiveDocContext: (data: GlobalPluginData, pathname: string) => ActiveDocContext;
-export declare const getDocVersionSuggestions: (data: GlobalPluginData, pathname: string) => DocVersionSuggestions;
+export declare function getActiveVersion(data: GlobalPluginData, pathname: string): GlobalVersion | undefined;
+export declare function getActiveDocContext(data: GlobalPluginData, pathname: string): ActiveDocContext;
+export declare function getDocVersionSuggestions(data: GlobalPluginData, pathname: string): DocVersionSuggestions;

package/lib/client/docsClientUtils.js

@@ -34,9 +34,7 @@ function getActivePlugin(allPluginData, pathname, options = {}) {
 exports.getActivePlugin = getActivePlugin;
 const getLatestVersion = (data) => data.versions.find((version) => version.isLast);
 exports.getLatestVersion = getLatestVersion;
-// Note: return undefined on doc-unrelated pages,
-// because there's no version currently considered as active
-const getActiveVersion = (data, pathname) => {
+function getActiveVersion(data, pathname) {
     const lastVersion = (0, exports.getLatestVersion)(data);
     // Last version is a route like /docs/*,
     // we need to match it last or it would match /docs/version-1.0/* as well
@@ -49,10 +47,10 @@ const getActiveVersion = (data, pathname) => {
         exact: false,
         strict: false,
     }));
-};
+}
 exports.getActiveVersion = getActiveVersion;
-const getActiveDocContext = (data, pathname) => {
-    const activeVersion = (0, exports.getActiveVersion)(data, pathname);
+function getActiveDocContext(data, pathname) {
+    const activeVersion = getActiveVersion(data, pathname);
     const activeDoc = activeVersion?.docs.find((doc) => !!(0, router_1.matchPath)(pathname, {
         path: doc.path,
         exact: true,
@@ -77,12 +75,12 @@ const getActiveDocContext = (data, pathname) => {
         activeDoc,
         alternateDocVersions: alternateVersionDocs,
     };
-};
+}
 exports.getActiveDocContext = getActiveDocContext;
-const getDocVersionSuggestions = (data, pathname) => {
+function getDocVersionSuggestions(data, pathname) {
     const latestVersion = (0, exports.getLatestVersion)(data);
-    const activeDocContext = (0, exports.getActiveDocContext)(data, pathname);
+    const activeDocContext = getActiveDocContext(data, pathname);
     const latestDocSuggestion = activeDocContext?.alternateDocVersions[latestVersion.name];
     return { latestDocSuggestion, latestVersionSuggestion: latestVersion };
-};
+}
 exports.getDocVersionSuggestions = getDocVersionSuggestions;

package/lib/client/index.d.ts

@@ -10,13 +10,13 @@ export declare const useAllDocsData: () => {
     [pluginId: string]: GlobalPluginData;
 };
 export declare const useDocsData: (pluginId: string | undefined) => GlobalPluginData;
-export declare const useActivePlugin: (options?: UseDataOptions) => ActivePlugin | undefined;
-export declare const useActivePluginAndVersion: (options?: UseDataOptions) => {
+export declare function useActivePlugin(options?: UseDataOptions): ActivePlugin | undefined;
+export declare function useActivePluginAndVersion(options?: UseDataOptions): {
     activePlugin: ActivePlugin;
     activeVersion: GlobalVersion | undefined;
 } | undefined;
-export declare const useVersions: (pluginId: string | undefined) => GlobalVersion[];
-export declare const useLatestVersion: (pluginId: string | undefined) => GlobalVersion;
-export declare const useActiveVersion: (pluginId: string | undefined) => GlobalVersion | undefined;
-export declare const useActiveDocContext: (pluginId: string | undefined) => ActiveDocContext;
-export declare const useDocVersionSuggestions: (pluginId: string | undefined) => DocVersionSuggestions;
+export declare function useVersions(pluginId: string | undefined): GlobalVersion[];
+export declare function useLatestVersion(pluginId: string | undefined): GlobalVersion;
+export declare function useActiveVersion(pluginId: string | undefined): GlobalVersion | undefined;
+export declare function useActiveDocContext(pluginId: string | undefined): ActiveDocContext;
+export declare function useDocVersionSuggestions(pluginId: string | undefined): DocVersionSuggestions;

package/lib/client/index.js

@@ -23,54 +23,50 @@ const useDocsData = (pluginId) => (0, useGlobalData_1.usePluginData)('docusaurus
 });
 exports.useDocsData = useDocsData;
 // TODO this feature should be provided by docusaurus core
-const useActivePlugin = (options = {}) => {
+function useActivePlugin(options = {}) {
     const data = (0, exports.useAllDocsData)();
     const { pathname } = (0, router_1.useLocation)();
     return (0, docsClientUtils_1.getActivePlugin)(data, pathname, options);
-};
+}
 exports.useActivePlugin = useActivePlugin;
-const useActivePluginAndVersion = (options = {}) => {
-    const activePlugin = (0, exports.useActivePlugin)(options);
+function useActivePluginAndVersion(options = {}) {
+    const activePlugin = useActivePlugin(options);
     const { pathname } = (0, router_1.useLocation)();
-    if (activePlugin) {
-        const activeVersion = (0, docsClientUtils_1.getActiveVersion)(activePlugin.pluginData, pathname);
-        return {
-            activePlugin,
-            activeVersion,
-        };
+    if (!activePlugin) {
+        return undefined;
     }
-    return undefined;
-};
+    const activeVersion = (0, docsClientUtils_1.getActiveVersion)(activePlugin.pluginData, pathname);
+    return {
+        activePlugin,
+        activeVersion,
+    };
+}
 exports.useActivePluginAndVersion = useActivePluginAndVersion;
-// versions are returned ordered (most recent first)
-const useVersions = (pluginId) => {
+function useVersions(pluginId) {
     const data = (0, exports.useDocsData)(pluginId);
     return data.versions;
-};
+}
 exports.useVersions = useVersions;
-const useLatestVersion = (pluginId) => {
+function useLatestVersion(pluginId) {
     const data = (0, exports.useDocsData)(pluginId);
     return (0, docsClientUtils_1.getLatestVersion)(data);
-};
+}
 exports.useLatestVersion = useLatestVersion;
-// Note: return undefined on doc-unrelated pages,
-// because there's no version currently considered as active
-const useActiveVersion = (pluginId) => {
+function useActiveVersion(pluginId) {
     const data = (0, exports.useDocsData)(pluginId);
     const { pathname } = (0, router_1.useLocation)();
     return (0, docsClientUtils_1.getActiveVersion)(data, pathname);
-};
+}
 exports.useActiveVersion = useActiveVersion;
-const useActiveDocContext = (pluginId) => {
+function useActiveDocContext(pluginId) {
     const data = (0, exports.useDocsData)(pluginId);
     const { pathname } = (0, router_1.useLocation)();
     return (0, docsClientUtils_1.getActiveDocContext)(data, pathname);
-};
+}
 exports.useActiveDocContext = useActiveDocContext;
-// Useful to say "hey, you are not on the latest docs version, please switch"
-const useDocVersionSuggestions = (pluginId) => {
+function useDocVersionSuggestions(pluginId) {
     const data = (0, exports.useDocsData)(pluginId);
     const { pathname } = (0, router_1.useLocation)();
     return (0, docsClientUtils_1.getDocVersionSuggestions)(data, pathname);
-};
+}
 exports.useDocVersionSuggestions = useDocVersionSuggestions;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/plugin-content-docs",
-  "version": "0.0.0-4853",
+  "version": "0.0.0-4855",
   "description": "Docs plugin for Docusaurus.",
   "main": "lib/index.js",
   "sideEffects": false,
@@ -24,11 +24,11 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/core": "0.0.0-4853",
-    "@docusaurus/logger": "0.0.0-4853",
-    "@docusaurus/mdx-loader": "0.0.0-4853",
-    "@docusaurus/utils": "0.0.0-4853",
-    "@docusaurus/utils-validation": "0.0.0-4853",
+    "@docusaurus/core": "0.0.0-4855",
+    "@docusaurus/logger": "0.0.0-4855",
+    "@docusaurus/mdx-loader": "0.0.0-4855",
+    "@docusaurus/utils": "0.0.0-4855",
+    "@docusaurus/utils-validation": "0.0.0-4855",
     "combine-promises": "^1.1.0",
     "fs-extra": "^10.0.1",
     "import-fresh": "^3.3.0",
@@ -40,8 +40,8 @@
     "webpack": "^5.72.0"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "0.0.0-4853",
-    "@docusaurus/types": "0.0.0-4853",
+    "@docusaurus/module-type-aliases": "0.0.0-4855",
+    "@docusaurus/types": "0.0.0-4855",
     "@types/js-yaml": "^4.0.5",
     "@types/picomatch": "^2.3.0",
     "commander": "^5.1.0",
@@ -57,5 +57,5 @@
   "engines": {
     "node": ">=14"
   },
-  "gitHead": "4b716dd2a6d3cbe3516aac8ca20e7f9c61504f46"
+  "gitHead": "9cfea8db2f22d348706de240a56303bb257d16b6"
 }

package/src/client/docsClientUtils.ts

@@ -59,12 +59,10 @@ export function getActivePlugin(
 export const getLatestVersion = (data: GlobalPluginData): GlobalVersion =>
   data.versions.find((version) => version.isLast)!;
 
-// Note: return undefined on doc-unrelated pages,
-// because there's no version currently considered as active
-export const getActiveVersion = (
+export function getActiveVersion(
   data: GlobalPluginData,
   pathname: string,
-): GlobalVersion | undefined => {
+): GlobalVersion | undefined {
   const lastVersion = getLatestVersion(data);
   // Last version is a route like /docs/*,
   // we need to match it last or it would match /docs/version-1.0/* as well
@@ -80,12 +78,12 @@ export const getActiveVersion = (
         strict: false,
       }),
   );
-};
+}
 
-export const getActiveDocContext = (
+export function getActiveDocContext(
   data: GlobalPluginData,
   pathname: string,
-): ActiveDocContext => {
+): ActiveDocContext {
   const activeVersion = getActiveVersion(data, pathname);
   const activeDoc = activeVersion?.docs.find(
     (doc) =>
@@ -119,15 +117,15 @@ export const getActiveDocContext = (
     activeDoc,
     alternateDocVersions: alternateVersionDocs,
   };
-};
+}
 
-export const getDocVersionSuggestions = (
+export function getDocVersionSuggestions(
   data: GlobalPluginData,
   pathname: string,
-): DocVersionSuggestions => {
+): DocVersionSuggestions {
   const latestVersion = getLatestVersion(data);
   const activeDocContext = getActiveDocContext(data, pathname);
   const latestDocSuggestion: GlobalDoc | undefined =
     activeDocContext?.alternateDocVersions[latestVersion.name];
   return {latestDocSuggestion, latestVersionSuggestion: latestVersion};
-};
+}

package/src/client/index.ts

@@ -43,67 +43,61 @@ export const useDocsData = (pluginId: string | undefined): GlobalPluginData =>
   }) as GlobalPluginData;
 
 // TODO this feature should be provided by docusaurus core
-export const useActivePlugin = (
+export function useActivePlugin(
   options: UseDataOptions = {},
-): ActivePlugin | undefined => {
+): ActivePlugin | undefined {
   const data = useAllDocsData();
   const {pathname} = useLocation();
   return getActivePlugin(data, pathname, options);
-};
+}
 
-export const useActivePluginAndVersion = (
+export function useActivePluginAndVersion(
   options: UseDataOptions = {},
 ):
-  | undefined
-  | {activePlugin: ActivePlugin; activeVersion: GlobalVersion | undefined} => {
+  | {activePlugin: ActivePlugin; activeVersion: GlobalVersion | undefined}
+  | undefined {
   const activePlugin = useActivePlugin(options);
   const {pathname} = useLocation();
-  if (activePlugin) {
-    const activeVersion = getActiveVersion(activePlugin.pluginData, pathname);
-    return {
-      activePlugin,
-      activeVersion,
-    };
+  if (!activePlugin) {
+    return undefined;
   }
-  return undefined;
-};
+  const activeVersion = getActiveVersion(activePlugin.pluginData, pathname);
+  return {
+    activePlugin,
+    activeVersion,
+  };
+}
 
-// versions are returned ordered (most recent first)
-export const useVersions = (pluginId: string | undefined): GlobalVersion[] => {
+export function useVersions(pluginId: string | undefined): GlobalVersion[] {
   const data = useDocsData(pluginId);
   return data.versions;
-};
+}
 
-export const useLatestVersion = (
-  pluginId: string | undefined,
-): GlobalVersion => {
+export function useLatestVersion(pluginId: string | undefined): GlobalVersion {
   const data = useDocsData(pluginId);
   return getLatestVersion(data);
-};
+}
 
-// Note: return undefined on doc-unrelated pages,
-// because there's no version currently considered as active
-export const useActiveVersion = (
+export function useActiveVersion(
   pluginId: string | undefined,
-): GlobalVersion | undefined => {
+): GlobalVersion | undefined {
   const data = useDocsData(pluginId);
   const {pathname} = useLocation();
   return getActiveVersion(data, pathname);
-};
+}
 
-export const useActiveDocContext = (
+export function useActiveDocContext(
   pluginId: string | undefined,
-): ActiveDocContext => {
+): ActiveDocContext {
   const data = useDocsData(pluginId);
   const {pathname} = useLocation();
   return getActiveDocContext(data, pathname);
-};
+}
 
-// Useful to say "hey, you are not on the latest docs version, please switch"
-export const useDocVersionSuggestions = (
+export function useDocVersionSuggestions(
   pluginId: string | undefined,
-): DocVersionSuggestions => {
+): DocVersionSuggestions {
   const data = useDocsData(pluginId);
   const {pathname} = useLocation();
   return getDocVersionSuggestions(data, pathname);
-};
+}

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

@@ -554,56 +554,18 @@ declare module '@theme/DocBreadcrumbs' {
 
 declare module '@theme/DocPage' {
   import type {PropVersionMetadata} from '@docusaurus/plugin-content-docs';
-  import type {DocumentRoute} from '@theme/DocItem';
+  import type {RouteConfigComponentProps} from 'react-router-config';
+  import type {Required} from 'utility-types';
 
-  export interface Props {
-    readonly location: {readonly pathname: string};
+  export interface Props extends Required<RouteConfigComponentProps, 'route'> {
     readonly versionMetadata: PropVersionMetadata;
-    readonly route: {
-      readonly path: string;
-      readonly component: () => JSX.Element;
-      readonly routes: DocumentRoute[];
-    };
   }
 
   export default function DocPage(props: Props): JSX.Element;
 }
 
-declare module '@theme/DocPage/Layout' {
-  import type {ReactNode} from 'react';
-
-  export interface Props {
-    children: ReactNode;
-  }
-
-  export default function DocPageLayout(props: Props): JSX.Element;
-}
-
-declare module '@theme/DocPage/Layout/Aside' {
-  import type {Dispatch, SetStateAction} from 'react';
-  import type {PropSidebar} from '@docusaurus/plugin-content-docs';
-
-  export interface Props {
-    sidebar: PropSidebar;
-    hiddenSidebarContainer: boolean;
-    setHiddenSidebarContainer: Dispatch<SetStateAction<boolean>>;
-  }
-
-  export default function DocPageLayoutAside(props: Props): JSX.Element;
-}
-
-declare module '@theme/DocPage/Layout/Main' {
-  import type {ReactNode} from 'react';
-
-  export interface Props {
-    hiddenSidebarContainer: boolean;
-    children: ReactNode;
-  }
-
-  export default function DocPageLayoutMain(props: Props): JSX.Element;
-}
-
-// TODO until TS supports exports field... hope it's in 4.6
+// TODO TS only supports reading `exports` in 4.7. We will need to merge the
+// type defs (and JSDoc) here with the implementation after that
 declare module '@docusaurus/plugin-content-docs/client' {
   import type {UseDataOptions} from '@docusaurus/types';
 
@@ -617,6 +579,11 @@ declare module '@docusaurus/plugin-content-docs/client' {
     alternateDocVersions: {[versionName: string]: GlobalDoc};
   };
   export type GlobalDoc = {
+    /**
+     * For generated index pages, this is the `slug`, **not** `permalink`
+     * (without base URL). Because slugs have leading slashes but IDs don't,
+     * there won't be clashes.
+     */
     id: string;
     path: string;
     sidebar: string | undefined;
@@ -627,7 +594,8 @@ declare module '@docusaurus/plugin-content-docs/client' {
     label: string;
     isLast: boolean;
     path: string;
-    mainDocId: string; // home doc (if docs homepage configured), or first doc
+    /** The doc with `slug: /`, or first doc in first sidebar */
+    mainDocId: string;
     docs: GlobalDoc[];
     sidebars?: {[sidebarId: string]: GlobalSidebar};
   };
@@ -645,9 +613,9 @@ declare module '@docusaurus/plugin-content-docs/client' {
     breadcrumbs: boolean;
   };
   export type DocVersionSuggestions = {
-    // suggest the latest version
+    /** suggest the latest version */
     latestVersionSuggestion: GlobalVersion;
-    // suggest the same doc, in latest version (if exist)
+    /** suggest the same doc, in latest version (if exist) */
     latestDocSuggestion?: GlobalDoc;
   };
 
@@ -661,12 +629,20 @@ declare module '@docusaurus/plugin-content-docs/client' {
   ) =>
     | {activePlugin: ActivePlugin; activeVersion: GlobalVersion | undefined}
     | undefined;
+  /** Versions are returned ordered (most recent first). */
   export const useVersions: (pluginId?: string) => GlobalVersion[];
   export const useLatestVersion: (pluginId?: string) => GlobalVersion;
+  /**
+   * Returns `undefined` on doc-unrelated pages, because there's no version
+   * currently considered as active.
+   */
   export const useActiveVersion: (
     pluginId?: string,
   ) => GlobalVersion | undefined;
   export const useActiveDocContext: (pluginId?: string) => ActiveDocContext;
+  /**
+   * Useful to say "hey, you are not on the latest docs version, please switch"
+   */
   export const useDocVersionSuggestions: (
     pluginId?: string,
   ) => DocVersionSuggestions;