fix(v2): alpha 62 doc fixes (#3381)

* deprecated nextVersionLabel option

* useActivePlugin failfast option

* remove deprecated option nextVersionLabel

* routeBasePath: '' should be forbidden

* routeBasePath: '' should be forbidden

* Docs: do not show version badge if there is only 1 version: https://github.com/facebook/docusaurus/issues/3362

* allow sidebars file to not exist: fallback to empty sidebars
https://githu.com/facebook/docusaurus/issues/3366

packages/docusaurus-plugin-content-docs/src/__tests__/sidebars.test.ts

@@ -115,9 +115,13 @@ describe('loadSidebars', () => {
   });
 
   test('unexisting path', () => {
+    /*
     expect(() => loadSidebars('badpath')).toThrowErrorMatchingInlineSnapshot(
       `"No sidebar file exist at path: badpath"`,
     );
+     */
+    // See https://github.com/facebook/docusaurus/issues/3366
+    expect(loadSidebars('badpath')).toEqual({});
   });
 
   test('undefined path', () => {

packages/docusaurus-plugin-content-docs/src/client/__tests__/docsClientUtils.test.ts

@@ -32,6 +32,17 @@ describe('docsClientUtils', () => {
     expect(getActivePlugin(data, '/')).toEqual(undefined);
     expect(getActivePlugin(data, '/xyz')).toEqual(undefined);
 
+    expect(() =>
+      getActivePlugin(data, '/', {failfast: true}),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `"Can't find active docs plugin for 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: /ios, /android"`,
+    );
+    expect(() =>
+      getActivePlugin(data, '/xyz', {failfast: true}),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `"Can't find active docs plugin for pathname=/xyz, 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: /ios, /android"`,
+    );
+
     const activePluginIos: ActivePlugin = {
       pluginId: 'pluginIosId',
       pluginData: data.pluginIosId,
@@ -115,6 +126,9 @@ describe('docsClientUtils', () => {
         },
       ],
     };
+
+    expect(getActiveVersion(data, '/someUnknownPath')).toEqual(undefined);
+
     expect(getActiveVersion(data, '/docs/next')?.name).toEqual('next');
     expect(getActiveVersion(data, '/docs/next/')?.name).toEqual('next');
     expect(getActiveVersion(data, '/docs/next/someDoc')?.name).toEqual('next');

packages/docusaurus-plugin-content-docs/src/client/docsClientUtils.ts

@@ -20,13 +20,27 @@ export type ActivePlugin = {
   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 const getActivePlugin = (
+export function getActivePlugin(
   allPluginDatas: Record<string, GlobalPluginData>,
   pathname: string,
-): ActivePlugin | undefined => {
+  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>,
+  pathname: string,
+  options: GetActivePluginOptions = {},
+): ActivePlugin | undefined {
   const activeEntry = Object.entries(allPluginDatas).find(
     ([_id, pluginData]) => {
       return !!matchPath(pathname, {
@@ -37,10 +51,22 @@ export const getActivePlugin = (
     },
   );
 
-  return activeEntry
+  const activePlugin: ActivePlugin | undefined = activeEntry
     ? {pluginId: activeEntry[0], pluginData: activeEntry[1]}
     : undefined;
-};
+
+  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,
+      )
+        .map((plugin) => plugin.path)
+        .join(', ')}`,
+    );
+  }
+
+  return activePlugin;
+}
 
 export type ActiveDocContext = {
   activeVersion?: Version;

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

@@ -200,9 +200,14 @@ export function loadSidebars(sidebarFilePath: string): Sidebars {
   if (!sidebarFilePath) {
     throw new Error(`sidebarFilePath not provided: ${sidebarFilePath}`);
   }
+
+  // sidebars file is optional, some users use docs without sidebars!
+  // See https://github.com/facebook/docusaurus/issues/3366
   if (!fs.existsSync(sidebarFilePath)) {
-    throw new Error(`No sidebar file exist at path: ${sidebarFilePath}`);
+    // throw new Error(`No sidebar file exist at path: ${sidebarFilePath}`);
+    return {};
   }
+
   // We don't want sidebars to be cached because of hot reloading.
   const sidebarJson = importFresh(sidebarFilePath) as SidebarsJSON;
   return normalizeSidebars(sidebarJson);

packages/docusaurus-plugin-content-docs/src/theme/hooks/useDocs.ts

@@ -18,6 +18,7 @@ import {
   getActiveVersion,
   getActiveDocContext,
   getDocVersionSuggestions,
+  GetActivePluginOptions,
 } from '../../client/docsClientUtils';
 
 const useAllDocsData = (): Record<string, GlobalPluginData> =>
@@ -26,10 +27,10 @@ const useAllDocsData = (): Record<string, GlobalPluginData> =>
 const useDocsData = (pluginId: string | undefined) =>
   usePluginData('docusaurus-plugin-content-docs', pluginId) as GlobalPluginData;
 
-export const useActivePlugin = () => {
+export const useActivePlugin = (options: GetActivePluginOptions = {}) => {
   const data = useAllDocsData();
   const {pathname} = useLocation();
-  return getActivePlugin(data, pathname);
+  return getActivePlugin(data, pathname, options);
 };
 
 // versions are returned ordered (most recent first)

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

@@ -24,6 +24,7 @@ import {DEFAULT_PLUGIN_ID} from '@docusaurus/core/lib/constants';
 import {LoadContext} from '@docusaurus/types';
 import {normalizeUrl} from '@docusaurus/utils';
 import {difference} from 'lodash';
+import chalk from 'chalk';
 
 // retro-compatibility: no prefix for the default plugin id
 function addPluginIdPrefix(fileOrDir: string, pluginId: string): string {
@@ -222,9 +223,13 @@ function checkVersionMetadataPaths({
       `The docs folder does not exist for version [${versionName}]. A docs folder is expected to be found at ${docsDirPath}`,
     );
   }
+
+  // See https://github.com/facebook/docusaurus/issues/3366
   if (!fs.existsSync(sidebarFilePath)) {
-    throw new Error(
-      `The sidebar file does not exist for version [${versionName}]. A sidebar file is expected to be found at ${sidebarFilePath}`,
+    console.log(
+      chalk.yellow(
+        `The sidebar file of docs version [${versionName}] does not exist. It is optional, but should rather be provided at ${sidebarFilePath}`,
+      ),
     );
   }
 }