@docusaurus/plugin-content-docs 2.0.0-beta.1ec2c95e3 → 2.0.0-beta.21

package/src/client/docsClientUtils.ts

@@ -7,49 +7,37 @@
 
 import {matchPath} from '@docusaurus/router';
 
-import {GlobalPluginData, GlobalVersion, GlobalDoc} from '../types';
+import type {
+  GlobalPluginData,
+  GlobalVersion,
+  GlobalDoc,
+  ActivePlugin,
+  ActiveDocContext,
+  DocVersionSuggestions,
+} from '@docusaurus/plugin-content-docs/client';
+import type {UseDataOptions} from '@docusaurus/types';
 
 // This code is not part of the api surface, not in ./theme on purpose
 
-// Short/convenient type aliases
-type Version = GlobalVersion;
-type Doc = GlobalDoc;
-
-export type ActivePlugin = {
-  pluginId: string;
-  pluginData: GlobalPluginData;
-};
-
-export type GetActivePluginOptions = {failfast?: boolean};
-
 // get the data of the plugin that is currently "active"
 // ie the docs of that plugin are currently browsed
 // it is useful to support multiple docs plugin instances
 export function getActivePlugin(
-  allPluginDatas: Record<string, GlobalPluginData>,
-  pathname: string,
-  options: {failfast: true}, // use fail-fast option if you know for sure one plugin instance is active
-): ActivePlugin;
-export function getActivePlugin(
-  allPluginDatas: Record<string, GlobalPluginData>,
-  pathname: string,
-  options?: GetActivePluginOptions,
-): ActivePlugin | undefined;
-
-export function getActivePlugin(
-  allPluginDatas: Record<string, GlobalPluginData>,
+  allPluginData: {[pluginId: string]: GlobalPluginData},
   pathname: string,
-  options: GetActivePluginOptions = {},
+  options: UseDataOptions = {},
 ): ActivePlugin | undefined {
-  const activeEntry = Object.entries(allPluginDatas).find(
-    ([_id, pluginData]) => {
-      return !!matchPath(pathname, {
-        path: pluginData.path,
-        exact: false,
-        strict: false,
-      });
-    },
-  );
+  const activeEntry = Object.entries(allPluginData)
+    // Route sorting: '/android/foo' should match '/android' instead of '/'
+    .sort((a, b) => b[1].path.localeCompare(a[1].path))
+    .find(
+      ([, pluginData]) =>
+        !!matchPath(pathname, {
+          path: pluginData.path,
+          exact: false,
+          strict: false,
+        }),
+    );
 
   const activePlugin: ActivePlugin | undefined = activeEntry
     ? {pluginId: activeEntry[0], pluginData: activeEntry[1]}
@@ -58,7 +46,7 @@ export function getActivePlugin(
   if (!activePlugin && options.failfast) {
     throw new Error(
       `Can't find active docs plugin for "${pathname}" pathname, while it was expected to be found. Maybe you tried to use a docs feature that can only be used on a docs-related page? Existing docs plugin paths are: ${Object.values(
-        allPluginDatas,
+        allPluginData,
       )
         .map((plugin) => plugin.path)
         .join(', ')}`,
@@ -68,42 +56,34 @@ export function getActivePlugin(
   return activePlugin;
 }
 
-export type ActiveDocContext = {
-  activeVersion?: Version;
-  activeDoc?: Doc;
-  alternateDocVersions: Record<string, Doc>;
-};
-
-export const getLatestVersion = (data: GlobalPluginData): Version => {
-  return data.versions.find((version) => version.isLast)!;
-};
+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,
-): Version | undefined => {
+): GlobalVersion | undefined {
   const lastVersion = getLatestVersion(data);
   // Last version is a route like /docs/*,
-  // we need to try to match it last or it would match /docs/version-1.0/* as well
+  // we need to match it last or it would match /docs/version-1.0/* as well
   const orderedVersionsMetadata = [
     ...data.versions.filter((version) => version !== lastVersion),
     lastVersion,
   ];
-  return orderedVersionsMetadata.find((version) => {
-    return !!matchPath(pathname, {
-      path: version.path,
-      exact: false,
-      strict: false,
-    });
-  });
-};
+  return orderedVersionsMetadata.find(
+    (version) =>
+      !!matchPath(pathname, {
+        path: version.path,
+        exact: false,
+        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) =>
@@ -137,22 +117,15 @@ export const getActiveDocContext = (
     activeDoc,
     alternateDocVersions: alternateVersionDocs,
   };
-};
-
-export type DocVersionSuggestions = {
-  // suggest the latest version
-  latestVersionSuggestion: GlobalVersion;
-  // suggest the same doc, in latest version (if exist)
-  latestDocSuggestion?: GlobalDoc;
-};
+}
 
-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];
+    activeDocContext.alternateDocVersions[latestVersion.name];
   return {latestDocSuggestion, latestVersionSuggestion: latestVersion};
-};
+}

package/src/client/index.ts

@@ -0,0 +1,106 @@
+/**
+ * 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 {useLocation} from '@docusaurus/router';
+import {
+  useAllPluginInstancesData,
+  usePluginData,
+} from '@docusaurus/useGlobalData';
+
+import {
+  getActivePlugin,
+  getLatestVersion,
+  getActiveVersion,
+  getActiveDocContext,
+  getDocVersionSuggestions,
+} from './docsClientUtils';
+import type {
+  GlobalPluginData,
+  GlobalVersion,
+  ActivePlugin,
+  ActiveDocContext,
+  DocVersionSuggestions,
+} from '@docusaurus/plugin-content-docs/client';
+import type {UseDataOptions} from '@docusaurus/types';
+
+// Important to use a constant object to avoid React useEffect executions etc.
+// see https://github.com/facebook/docusaurus/issues/5089
+const StableEmptyObject = {};
+
+// In blog-only mode, docs hooks are still used by the theme. We need a fail-
+// safe fallback when the docs plugin is not in use
+export const useAllDocsData = (): {[pluginId: string]: GlobalPluginData} =>
+  (useAllPluginInstancesData('docusaurus-plugin-content-docs') as
+    | {
+        [pluginId: string]: GlobalPluginData;
+      }
+    | undefined) ?? StableEmptyObject;
+
+export const useDocsData = (pluginId: string | undefined): GlobalPluginData =>
+  usePluginData('docusaurus-plugin-content-docs', pluginId, {
+    failfast: true,
+  }) as GlobalPluginData;
+
+// TODO this feature should be provided by docusaurus core
+export function useActivePlugin(
+  options: UseDataOptions = {},
+): ActivePlugin | undefined {
+  const data = useAllDocsData();
+  const {pathname} = useLocation();
+  return getActivePlugin(data, pathname, options);
+}
+
+export function useActivePluginAndVersion(
+  options: UseDataOptions = {},
+):
+  | {activePlugin: ActivePlugin; activeVersion: GlobalVersion | undefined}
+  | undefined {
+  const activePlugin = useActivePlugin(options);
+  const {pathname} = useLocation();
+  if (!activePlugin) {
+    return undefined;
+  }
+  const activeVersion = getActiveVersion(activePlugin.pluginData, pathname);
+  return {
+    activePlugin,
+    activeVersion,
+  };
+}
+
+export function useVersions(pluginId: string | undefined): GlobalVersion[] {
+  const data = useDocsData(pluginId);
+  return data.versions;
+}
+
+export function useLatestVersion(pluginId: string | undefined): GlobalVersion {
+  const data = useDocsData(pluginId);
+  return getLatestVersion(data);
+}
+
+export function useActiveVersion(
+  pluginId: string | undefined,
+): GlobalVersion | undefined {
+  const data = useDocsData(pluginId);
+  const {pathname} = useLocation();
+  return getActiveVersion(data, pathname);
+}
+
+export function useActiveDocContext(
+  pluginId: string | undefined,
+): ActiveDocContext {
+  const data = useDocsData(pluginId);
+  const {pathname} = useLocation();
+  return getActiveDocContext(data, pathname);
+}
+
+export function useDocVersionSuggestions(
+  pluginId: string | undefined,
+): DocVersionSuggestions {
+  const data = useDocsData(pluginId);
+  const {pathname} = useLocation();
+  return getDocVersionSuggestions(data, pathname);
+}

package/src/constants.ts

@@ -5,9 +5,11 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-// The name of the version at the root of your site (website/docs)
+/** The name of the version that's actively worked on (e.g. `website/docs`) */
 export const CURRENT_VERSION_NAME = 'current';
-
+/** All doc versions are stored here by version names */
 export const VERSIONED_DOCS_DIR = 'versioned_docs';
+/** All doc versioned sidebars are stored here by version names */
 export const VERSIONED_SIDEBARS_DIR = 'versioned_sidebars';
+/** The version names. Should 1-1 map to the content of versioned docs dir. */
 export const VERSIONS_JSON_FILE = 'versions.json';

package/{types.d.ts → src/deps.d.ts}

@@ -6,7 +6,7 @@
  */
 
 declare module 'remark-admonitions' {
-  type Options = Record<string, unknown>;
+  type Options = {[key: string]: unknown};
 
   const plugin: (options?: Options) => void;
   export = plugin;