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

package/src/categoryGeneratedIndex.ts

@@ -5,7 +5,10 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import type {CategoryGeneratedIndexMetadata, DocMetadataBase} from './types';
+import type {
+  CategoryGeneratedIndexMetadata,
+  DocMetadataBase,
+} from '@docusaurus/plugin-content-docs';
 import type {SidebarItemCategoryWithGeneratedIndex} from './sidebars/types';
 import {type SidebarsUtils, toNavigationLink} from './sidebars/utils';
 import {createDocsByIdIndex} from './docs';
@@ -17,14 +20,10 @@ function getCategoryGeneratedIndexMetadata({
 }: {
   category: SidebarItemCategoryWithGeneratedIndex;
   sidebarsUtils: SidebarsUtils;
-  docsById: Record<string, DocMetadataBase>;
+  docsById: {[docId: string]: DocMetadataBase};
 }): CategoryGeneratedIndexMetadata {
   const {sidebarName, previous, next} =
     sidebarsUtils.getCategoryGeneratedIndexNavigation(category.link.permalink);
-  if (!sidebarName) {
-    throw new Error('unexpected');
-  }
-
   return {
     title: category.link.title ?? category.label,
     description: category.link.description,
@@ -32,9 +31,11 @@ function getCategoryGeneratedIndexMetadata({
     keywords: category.link.keywords,
     slug: category.link.slug,
     permalink: category.link.permalink,
-    sidebar: sidebarName,
-    previous: toNavigationLink(previous, docsById),
-    next: toNavigationLink(next, docsById),
+    sidebar: sidebarName!,
+    navigation: {
+      previous: toNavigationLink(previous, docsById),
+      next: toNavigationLink(next, docsById),
+    },
   };
 }
 

package/src/cli.ts

@@ -7,18 +7,19 @@
 
 import {
   getVersionsFilePath,
-  getVersionedDocsDirPath,
-  getVersionedSidebarsDirPath,
-} from './versions';
+  getVersionDocsDirPath,
+  getVersionSidebarsPath,
+  getDocsDirPathLocalized,
+} from './versions/files';
+import {validateVersionName} from './versions/validation';
 import fs from 'fs-extra';
 import path from 'path';
-import type {
-  PathOptions,
-  SidebarOptions,
-} from '@docusaurus/plugin-content-docs';
-import {loadSidebarsFileUnsafe, resolveSidebarPathOption} from './sidebars';
+import type {PluginOptions} from '@docusaurus/plugin-content-docs';
+import {loadSidebarsFileUnsafe} from './sidebars';
+import {CURRENT_VERSION_NAME} from './constants';
 import {DEFAULT_PLUGIN_ID} from '@docusaurus/utils';
 import logger from '@docusaurus/logger';
+import type {LoadContext} from '@docusaurus/types';
 
 async function createVersionedSidebarFile({
   siteDir,
@@ -42,14 +43,8 @@ async function createVersionedSidebarFile({
   const shouldCreateVersionedSidebarFile = Object.keys(sidebars).length > 0;
 
   if (shouldCreateVersionedSidebarFile) {
-    const versionedSidebarsDir = getVersionedSidebarsDirPath(siteDir, pluginId);
-    const newSidebarFile = path.join(
-      versionedSidebarsDir,
-      `version-${version}-sidebars.json`,
-    );
-    await fs.ensureDir(path.dirname(newSidebarFile));
-    await fs.writeFile(
-      newSidebarFile,
+    await fs.outputFile(
+      getVersionSidebarsPath(siteDir, pluginId, version),
       `${JSON.stringify(sidebars, null, 2)}\n`,
       'utf8',
     );
@@ -58,54 +53,27 @@ async function createVersionedSidebarFile({
 
 // Tests depend on non-default export for mocking.
 export async function cliDocsVersionCommand(
-  version: string | null | undefined,
-  siteDir: string,
-  pluginId: string,
-  options: PathOptions & SidebarOptions,
+  version: string,
+  {id: pluginId, path: docsPath, sidebarPath}: PluginOptions,
+  {siteDir, i18n}: LoadContext,
 ): Promise<void> {
   // It wouldn't be very user-friendly to show a [default] log prefix,
   // so we use [docs] instead of [default]
   const pluginIdLogPrefix =
     pluginId === DEFAULT_PLUGIN_ID ? '[docs]' : `[${pluginId}]`;
 
-  if (!version) {
-    throw new Error(
-      `${pluginIdLogPrefix}: no version tag specified! Pass the version you wish to create as an argument, for example: 1.0.0.`,
-    );
-  }
-
-  if (version.includes('/') || version.includes('\\')) {
-    throw new Error(
-      `${pluginIdLogPrefix}: invalid version tag specified! Do not include slash (/) or backslash (\\). Try something like: 1.0.0.`,
-    );
-  }
-
-  if (version.length > 32) {
-    throw new Error(
-      `${pluginIdLogPrefix}: invalid version tag specified! Length cannot exceed 32 characters. Try something like: 1.0.0.`,
-    );
-  }
-
-  // Since we are going to create `version-${version}` folder, we need to make
-  // sure it's a valid pathname.
-  // eslint-disable-next-line no-control-regex
-  if (/[<>:"|?*\x00-\x1F]/g.test(version)) {
-    throw new Error(
-      `${pluginIdLogPrefix}: invalid version tag specified! Please ensure its a valid pathname too. Try something like: 1.0.0.`,
-    );
-  }
-
-  if (/^\.\.?$/.test(version)) {
-    throw new Error(
-      `${pluginIdLogPrefix}: invalid version tag specified! Do not name your version "." or "..". Try something like: 1.0.0.`,
-    );
+  try {
+    validateVersionName(version);
+  } catch (e) {
+    logger.info`${pluginIdLogPrefix}: Invalid version name provided. Try something like: 1.0.0`;
+    throw e;
   }
 
   // Load existing versions.
   let versions = [];
   const versionsJSONFile = getVersionsFilePath(siteDir, pluginId);
   if (await fs.pathExists(versionsJSONFile)) {
-    versions = JSON.parse(await fs.readFile(versionsJSONFile, 'utf8'));
+    versions = await fs.readJSON(versionsJSONFile);
   }
 
   // Check if version already exists.
@@ -115,33 +83,60 @@ export async function cliDocsVersionCommand(
     );
   }
 
-  const {path: docsPath, sidebarPath} = options;
-
-  // Copy docs files.
-  const docsDir = path.join(siteDir, docsPath);
-
-  if (
-    (await fs.pathExists(docsDir)) &&
-    (await fs.readdir(docsDir)).length > 0
-  ) {
-    const versionedDir = getVersionedDocsDirPath(siteDir, pluginId);
-    const newVersionDir = path.join(versionedDir, `version-${version}`);
-    await fs.copy(docsDir, newVersionDir);
-  } else {
-    throw new Error(`${pluginIdLogPrefix}: there is no docs to version!`);
+  if (i18n.locales.length > 1) {
+    logger.info`Versioned docs will be created for the following locales: name=${i18n.locales}`;
   }
 
+  await Promise.all(
+    i18n.locales.map(async (locale) => {
+      // Copy docs files.
+      const docsDir =
+        locale === i18n.defaultLocale
+          ? path.resolve(siteDir, docsPath)
+          : getDocsDirPathLocalized({
+              siteDir,
+              locale,
+              pluginId,
+              versionName: CURRENT_VERSION_NAME,
+            });
+
+      if (
+        !(await fs.pathExists(docsDir)) ||
+        (await fs.readdir(docsDir)).length === 0
+      ) {
+        if (locale === i18n.defaultLocale) {
+          throw new Error(
+            logger.interpolate`${pluginIdLogPrefix}: no docs found in path=${docsDir}.`,
+          );
+        } else {
+          logger.warn`${pluginIdLogPrefix}: no docs found in path=${docsDir}. Skipping.`;
+          return;
+        }
+      }
+
+      const newVersionDir =
+        locale === i18n.defaultLocale
+          ? getVersionDocsDirPath(siteDir, pluginId, version)
+          : getDocsDirPathLocalized({
+              siteDir,
+              locale,
+              pluginId,
+              versionName: version,
+            });
+      await fs.copy(docsDir, newVersionDir);
+    }),
+  );
+
   await createVersionedSidebarFile({
     siteDir,
     pluginId,
     version,
-    sidebarPath: resolveSidebarPathOption(siteDir, sidebarPath),
+    sidebarPath,
   });
 
   // Update versions.json file.
   versions.unshift(version);
-  await fs.ensureDir(path.dirname(versionsJSONFile));
-  await fs.writeFile(
+  await fs.outputFile(
     versionsJSONFile,
     `${JSON.stringify(versions, null, 2)}\n`,
   );

package/src/client/docsClientUtils.ts

@@ -11,11 +11,11 @@ import type {
   GlobalPluginData,
   GlobalVersion,
   GlobalDoc,
-  GetActivePluginOptions,
   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
 
@@ -23,11 +23,11 @@ import type {
 // 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>,
+  allPluginData: {[pluginId: string]: GlobalPluginData},
   pathname: string,
-  options: GetActivePluginOptions = {},
+  options: UseDataOptions = {},
 ): ActivePlugin | undefined {
-  const activeEntry = Object.entries(allPluginDatas)
+  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(
@@ -46,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(', ')}`,
@@ -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

@@ -6,7 +6,10 @@
  */
 
 import {useLocation} from '@docusaurus/router';
-import useGlobalData, {usePluginData} from '@docusaurus/useGlobalData';
+import {
+  useAllPluginInstancesData,
+  usePluginData,
+} from '@docusaurus/useGlobalData';
 
 import {
   getActivePlugin,
@@ -21,84 +24,80 @@ import type {
   ActivePlugin,
   ActiveDocContext,
   DocVersionSuggestions,
-  GetActivePluginOptions,
 } 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 = {};
 
-// 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> =>
-  useGlobalData()['docusaurus-plugin-content-docs'] ?? 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') ??
+  StableEmptyObject;
 
 export const useDocsData = (pluginId: string | undefined): GlobalPluginData =>
-  usePluginData('docusaurus-plugin-content-docs', pluginId) as GlobalPluginData;
+  usePluginData('docusaurus-plugin-content-docs', pluginId, {
+    failfast: true,
+  }) as GlobalPluginData;
 
 // TODO this feature should be provided by docusaurus core
-export const useActivePlugin = (
-  options: GetActivePluginOptions = {},
-): ActivePlugin | undefined => {
+export function useActivePlugin(
+  options: UseDataOptions = {},
+): ActivePlugin | undefined {
   const data = useAllDocsData();
   const {pathname} = useLocation();
   return getActivePlugin(data, pathname, options);
-};
+}
 
-export const useActivePluginAndVersion = (
-  options: GetActivePluginOptions = {},
+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/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/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;