@docusaurus/plugin-content-docs 2.0.0-beta.15 → 2.0.0-beta.16

package/src/versions.ts

@@ -28,16 +28,14 @@ import {
   posixPath,
   DEFAULT_PLUGIN_ID,
 } from '@docusaurus/utils';
-import {difference} from 'lodash';
+import _ from 'lodash';
 import {resolveSidebarPathOption} from './sidebars';
 
 // retro-compatibility: no prefix for the default plugin id
 function addPluginIdPrefix(fileOrDir: string, pluginId: string): string {
-  if (pluginId === DEFAULT_PLUGIN_ID) {
-    return fileOrDir;
-  } else {
-    return `${pluginId}_${fileOrDir}`;
-  }
+  return pluginId === DEFAULT_PLUGIN_ID
+    ? fileOrDir
+    : `${pluginId}_${fileOrDir}`;
 }
 
 export function getVersionedDocsDirPath(
@@ -87,7 +85,7 @@ function ensureValidVersionArray(
   versionArray.forEach(ensureValidVersionString);
 }
 
-async function readVersionsFile(
+export async function readVersionsFile(
   siteDir: string,
   pluginId: string,
 ): Promise<string[] | null> {
@@ -96,12 +94,11 @@ async function readVersionsFile(
     const content = JSON.parse(await fs.readFile(versionsFilePath, 'utf8'));
     ensureValidVersionArray(content);
     return content;
-  } else {
-    return null;
   }
+  return null;
 }
 
-async function readVersionNames(
+export async function readVersionNames(
   siteDir: string,
   options: Pick<
     PluginOptions,
@@ -260,7 +257,7 @@ function getVersionEditUrls({
   };
 }
 
-function getDefaultVersionBanner({
+export function getDefaultVersionBanner({
   versionName,
   versionNames,
   lastVersionName,
@@ -274,18 +271,16 @@ function getDefaultVersionBanner({
     return null;
   }
   // Upcoming versions: unreleased banner
-  else if (
+  if (
     versionNames.indexOf(versionName) < versionNames.indexOf(lastVersionName)
   ) {
     return 'unreleased';
   }
   // Older versions: display unmaintained banner
-  else {
-    return 'unmaintained';
-  }
+  return 'unmaintained';
 }
 
-function getVersionBanner({
+export function getVersionBanner({
   versionName,
   versionNames,
   lastVersionName,
@@ -307,7 +302,7 @@ function getVersionBanner({
   });
 }
 
-function getVersionBadge({
+export function getVersionBadge({
   versionName,
   versionNames,
   options,
@@ -423,7 +418,7 @@ function createVersionMetadata({
   };
 }
 
-function checkVersionMetadataPaths({
+async function checkVersionMetadataPaths({
   versionMetadata,
   context,
 }: {
@@ -434,7 +429,7 @@ function checkVersionMetadataPaths({
   const {siteDir} = context;
   const isCurrentVersion = versionName === CURRENT_VERSION_NAME;
 
-  if (!fs.existsSync(contentPath)) {
+  if (!(await fs.pathExists(contentPath))) {
     throw new Error(
       `The docs folder does not exist for version "${versionName}". A docs folder is expected to be found at ${path.relative(
         siteDir,
@@ -443,14 +438,15 @@ function checkVersionMetadataPaths({
     );
   }
 
-  // If the current version defines a path to a sidebar file  that does not exist, we throw!
-  // Note: for versioned sidebars, the file may not exist (as we prefer to not create it rather than to create an empty file)
+  // If the current version defines a path to a sidebar file that does not
+  // exist, we throw! Note: for versioned sidebars, the file may not exist (as
+  // we prefer to not create it rather than to create an empty file)
   // See https://github.com/facebook/docusaurus/issues/3366
   // See https://github.com/facebook/docusaurus/pull/4775
   if (
     isCurrentVersion &&
     typeof sidebarFilePath === 'string' &&
-    !fs.existsSync(sidebarFilePath)
+    !(await fs.pathExists(sidebarFilePath))
   ) {
     throw new Error(`The path to the sidebar file does not exist at "${path.relative(
       siteDir,
@@ -469,11 +465,10 @@ Please set the docs "sidebarPath" field in your config file to:
 function getDefaultLastVersionName(versionNames: string[]) {
   if (versionNames.length === 1) {
     return versionNames[0];
-  } else {
-    return versionNames.filter(
-      (versionName) => versionName !== CURRENT_VERSION_NAME,
-    )[0];
   }
+  return versionNames.filter(
+    (versionName) => versionName !== CURRENT_VERSION_NAME,
+  )[0];
 }
 
 function checkVersionsOptions(
@@ -491,7 +486,7 @@ function checkVersionsOptions(
       `Docs option lastVersion: ${options.lastVersion} is invalid. ${availableVersionNamesMsg}`,
     );
   }
-  const unknownVersionConfigNames = difference(
+  const unknownVersionConfigNames = _.difference(
     Object.keys(options.versions),
     availableVersionNames,
   );
@@ -509,7 +504,7 @@ function checkVersionsOptions(
         `Invalid docs option "onlyIncludeVersions": an empty array is not allowed, at least one version is needed.`,
       );
     }
-    const unknownOnlyIncludeVersionNames = difference(
+    const unknownOnlyIncludeVersionNames = _.difference(
       options.onlyIncludeVersions,
       availableVersionNames,
     );
@@ -536,17 +531,16 @@ function checkVersionsOptions(
  * Note: we preserve the order in which versions are provided;
  * the order of the onlyIncludeVersions array does not matter
  */
-function filterVersions(
+export function filterVersions(
   versionNamesUnfiltered: string[],
   options: Pick<PluginOptions, 'onlyIncludeVersions'>,
-) {
+): string[] {
   if (options.onlyIncludeVersions) {
     return versionNamesUnfiltered.filter((name) =>
       (options.onlyIncludeVersions || []).includes(name),
     );
-  } else {
-    return versionNamesUnfiltered;
   }
+  return versionNamesUnfiltered;
 }
 
 export async function readVersionsMetadata({
@@ -591,8 +585,10 @@ export async function readVersionsMetadata({
       options,
     }),
   );
-  versionsMetadata.forEach((versionMetadata) =>
-    checkVersionMetadataPaths({versionMetadata, context}),
+  await Promise.all(
+    versionsMetadata.map((versionMetadata) =>
+      checkVersionMetadataPaths({versionMetadata, context}),
+    ),
   );
   return versionsMetadata;
 }

package/lib/client/globalDataHooks.d.ts

@@ -1,19 +0,0 @@
-/**
- * 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 type { GlobalPluginData, GlobalVersion, ActivePlugin, ActiveDocContext, DocVersionSuggestions, GetActivePluginOptions } from '@docusaurus/plugin-content-docs/client';
-export declare const useAllDocsData: () => Record<string, GlobalPluginData>;
-export declare const useDocsData: (pluginId: string | undefined) => GlobalPluginData;
-export declare const useActivePlugin: (options?: GetActivePluginOptions) => ActivePlugin | undefined;
-export declare const useActivePluginAndVersion: (options?: GetActivePluginOptions) => {
-    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;

package/lib/client/globalDataHooks.js

@@ -1,76 +0,0 @@
-"use strict";
-/**
- * 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.
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.useDocVersionSuggestions = exports.useActiveDocContext = exports.useActiveVersion = exports.useLatestVersion = exports.useVersions = exports.useActivePluginAndVersion = exports.useActivePlugin = exports.useDocsData = exports.useAllDocsData = void 0;
-const tslib_1 = require("tslib");
-const router_1 = require("@docusaurus/router");
-const useGlobalData_1 = (0, tslib_1.__importStar)(require("@docusaurus/useGlobalData"));
-const docsClientUtils_1 = require("./docsClientUtils");
-// Important to use a constant object to avoid React useEffect executions etc...,
-// see https://github.com/facebook/docusaurus/issues/5089
-const StableEmptyObject = {};
-// Not using useAllPluginInstancesData() because 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
-const useAllDocsData = () => { var _a; 
-// useAllPluginInstancesData('docusaurus-plugin-content-docs');
-return (_a = (0, useGlobalData_1.default)()['docusaurus-plugin-content-docs']) !== null && _a !== void 0 ? _a : StableEmptyObject; };
-exports.useAllDocsData = useAllDocsData;
-const useDocsData = (pluginId) => (0, useGlobalData_1.usePluginData)('docusaurus-plugin-content-docs', pluginId);
-exports.useDocsData = useDocsData;
-// TODO this feature should be provided by docusaurus core
-const 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);
-    const { pathname } = (0, router_1.useLocation)();
-    if (activePlugin) {
-        const activeVersion = (0, docsClientUtils_1.getActiveVersion)(activePlugin.pluginData, pathname);
-        return {
-            activePlugin,
-            activeVersion,
-        };
-    }
-    return undefined;
-};
-exports.useActivePluginAndVersion = useActivePluginAndVersion;
-// versions are returned ordered (most recent first)
-const useVersions = (pluginId) => {
-    const data = (0, exports.useDocsData)(pluginId);
-    return data.versions;
-};
-exports.useVersions = useVersions;
-const 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) => {
-    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) => {
-    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) => {
-    const data = (0, exports.useDocsData)(pluginId);
-    const { pathname } = (0, router_1.useLocation)();
-    return (0, docsClientUtils_1.getDocVersionSuggestions)(data, pathname);
-};
-exports.useDocVersionSuggestions = useDocVersionSuggestions;

package/src/client/globalDataHooks.ts

@@ -1,107 +0,0 @@
-/**
- * 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 useGlobalData, {
-  // useAllPluginInstancesData,
-  usePluginData,
-} from '@docusaurus/useGlobalData';
-
-import {
-  getActivePlugin,
-  getLatestVersion,
-  getActiveVersion,
-  getActiveDocContext,
-  getDocVersionSuggestions,
-} from './docsClientUtils';
-import type {
-  GlobalPluginData,
-  GlobalVersion,
-  ActivePlugin,
-  ActiveDocContext,
-  DocVersionSuggestions,
-  GetActivePluginOptions,
-} from '@docusaurus/plugin-content-docs/client';
-
-// Important to use a constant object to avoid React useEffect executions etc...,
-// see https://github.com/facebook/docusaurus/issues/5089
-const StableEmptyObject = {};
-
-// Not using useAllPluginInstancesData() because 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 = (): Record<string, GlobalPluginData> =>
-  // useAllPluginInstancesData('docusaurus-plugin-content-docs');
-  useGlobalData()['docusaurus-plugin-content-docs'] ?? StableEmptyObject;
-
-export const useDocsData = (pluginId: string | undefined): GlobalPluginData =>
-  usePluginData('docusaurus-plugin-content-docs', pluginId) as GlobalPluginData;
-
-// TODO this feature should be provided by docusaurus core
-export const useActivePlugin = (
-  options: GetActivePluginOptions = {},
-): ActivePlugin | undefined => {
-  const data = useAllDocsData();
-  const {pathname} = useLocation();
-  return getActivePlugin(data, pathname, options);
-};
-
-export const useActivePluginAndVersion = (
-  options: GetActivePluginOptions = {},
-):
-  | undefined
-  | {activePlugin: ActivePlugin; activeVersion: GlobalVersion | undefined} => {
-  const activePlugin = useActivePlugin(options);
-  const {pathname} = useLocation();
-  if (activePlugin) {
-    const activeVersion = getActiveVersion(activePlugin.pluginData, pathname);
-    return {
-      activePlugin,
-      activeVersion,
-    };
-  }
-  return undefined;
-};
-
-// versions are returned ordered (most recent first)
-export const useVersions = (pluginId: string | undefined): GlobalVersion[] => {
-  const data = useDocsData(pluginId);
-  return data.versions;
-};
-
-export const 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 = (
-  pluginId: string | undefined,
-): GlobalVersion | undefined => {
-  const data = useDocsData(pluginId);
-  const {pathname} = useLocation();
-  return getActiveVersion(data, pathname);
-};
-
-export const useActiveDocContext = (
-  pluginId: string | undefined,
-): 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 = (
-  pluginId: string | undefined,
-): DocVersionSuggestions => {
-  const data = useDocsData(pluginId);
-  const {pathname} = useLocation();
-  return getDocVersionSuggestions(data, pathname);
-};