@docusaurus/plugin-content-docs 2.0.0-beta.ff31de0ff → 2.0.0-rc.1

package/src/cli.ts

@@ -5,22 +5,24 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import {
-  getVersionsFilePath,
-  getVersionedDocsDirPath,
-  getVersionedSidebarsDirPath,
-} from './versions';
 import fs from 'fs-extra';
 import path from 'path';
+import logger from '@docusaurus/logger';
+import {DEFAULT_PLUGIN_ID} from '@docusaurus/utils';
 import {
-  PathOptions,
-  UnprocessedSidebarItem,
-  UnprocessedSidebars,
-} from './types';
-import {loadSidebars} from './sidebars';
-import {DEFAULT_PLUGIN_ID} from '@docusaurus/core/lib/constants';
-
-function createVersionedSidebarFile({
+  getVersionsFilePath,
+  getVersionDocsDirPath,
+  getVersionSidebarsPath,
+  getDocsDirPathLocalized,
+  readVersionsFile,
+} from './versions/files';
+import {validateVersionName} from './versions/validation';
+import {loadSidebarsFileUnsafe} from './sidebars';
+import {CURRENT_VERSION_NAME} from './constants';
+import type {PluginOptions} from '@docusaurus/plugin-content-docs';
+import type {LoadContext} from '@docusaurus/types';
+
+async function createVersionedSidebarFile({
   siteDir,
   pluginId,
   sidebarPath,
@@ -32,133 +34,111 @@ function createVersionedSidebarFile({
   version: string;
 }) {
   // Load current sidebar and create a new versioned sidebars file (if needed).
-  const loadedSidebars = loadSidebars(sidebarPath);
+  // Note: we don't need the sidebars file to be normalized: it's ok to let
+  // plugin option changes to impact older, versioned sidebars
+  // We don't validate here, assuming the user has already built the version
+  const sidebars = await loadSidebarsFileUnsafe(sidebarPath);
 
-  // Do not create a useless versioned sidebars file if sidebars file is empty or sidebars are disabled/false)
-  const shouldCreateVersionedSidebarFile =
-    Object.keys(loadedSidebars).length > 0;
+  // Do not create a useless versioned sidebars file if sidebars file is empty
+  // or sidebars are disabled/false)
+  const shouldCreateVersionedSidebarFile = Object.keys(sidebars).length > 0;
 
   if (shouldCreateVersionedSidebarFile) {
-    // TODO @slorber: this "version prefix" in versioned sidebars looks like a bad idea to me
-    // TODO try to get rid of it
-    // Transform id in original sidebar to versioned id.
-    const normalizeItem = (
-      item: UnprocessedSidebarItem,
-    ): UnprocessedSidebarItem => {
-      switch (item.type) {
-        case 'category':
-          return {...item, items: item.items.map(normalizeItem)};
-        case 'ref':
-        case 'doc':
-          return {
-            type: item.type,
-            id: `version-${version}/${item.id}`,
-          };
-        default:
-          return item;
-      }
-    };
-
-    const versionedSidebar: UnprocessedSidebars = Object.entries(
-      loadedSidebars,
-    ).reduce((acc: UnprocessedSidebars, [sidebarId, sidebarItems]) => {
-      const newVersionedSidebarId = `version-${version}/${sidebarId}`;
-      acc[newVersionedSidebarId] = sidebarItems.map(normalizeItem);
-      return acc;
-    }, {});
-
-    const versionedSidebarsDir = getVersionedSidebarsDirPath(siteDir, pluginId);
-    const newSidebarFile = path.join(
-      versionedSidebarsDir,
-      `version-${version}-sidebars.json`,
-    );
-    fs.ensureDirSync(path.dirname(newSidebarFile));
-    fs.writeFileSync(
-      newSidebarFile,
-      `${JSON.stringify(versionedSidebar, null, 2)}\n`,
+    await fs.outputFile(
+      getVersionSidebarsPath(siteDir, pluginId, version),
+      `${JSON.stringify(sidebars, null, 2)}\n`,
       'utf8',
     );
   }
 }
 
 // Tests depend on non-default export for mocking.
-// eslint-disable-next-line import/prefer-default-export
-export function cliDocsVersionCommand(
-  version: string | null | undefined,
-  siteDir: string,
-  pluginId: string,
-  options: PathOptions,
-): void {
+export async function cliDocsVersionCommand(
+  version: unknown,
+  {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. Ex: 1.0.0`,
-    );
-  }
-
-  if (version.includes('/') || version.includes('\\')) {
-    throw new Error(
-      `${pluginIdLogPrefix}Invalid version tag specified! Do not include slash (/) or (\\). Try something like: 1.0.0`,
-    );
-  }
+    pluginId === DEFAULT_PLUGIN_ID ? '[docs]' : `[${pluginId}]`;
 
-  if (version.length > 32) {
-    throw new Error(
-      `${pluginIdLogPrefix}Invalid version tag specified! Length must <= 32 characters. Try something like: 1.0.0`,
-    );
+  try {
+    validateVersionName(version);
+  } catch (err) {
+    logger.info`${pluginIdLogPrefix}: Invalid version name provided. Try something like: 1.0.0`;
+    throw err;
   }
 
-  // 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`,
-    );
-  }
-
-  // Load existing versions.
-  let versions = [];
-  const versionsJSONFile = getVersionsFilePath(siteDir, pluginId);
-  if (fs.existsSync(versionsJSONFile)) {
-    versions = JSON.parse(fs.readFileSync(versionsJSONFile, 'utf8'));
-  }
+  const versions = (await readVersionsFile(siteDir, pluginId)) ?? [];
 
   // Check if version already exists.
   if (versions.includes(version)) {
     throw new Error(
-      `${pluginIdLogPrefix}This version already exists!. Use a version tag that does not already exist.`,
+      `${pluginIdLogPrefix}: this version already exists! Use a version tag that does not already exist.`,
     );
   }
 
-  const {path: docsPath, sidebarPath} = options;
-
-  // Copy docs files.
-  const docsDir = path.join(siteDir, docsPath);
-  if (fs.existsSync(docsDir) && fs.readdirSync(docsDir).length > 0) {
-    const versionedDir = getVersionedDocsDirPath(siteDir, pluginId);
-    const newVersionDir = path.join(versionedDir, `version-${version}`);
-    fs.copySync(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}`;
   }
 
-  createVersionedSidebarFile({siteDir, pluginId, version, sidebarPath});
+  await Promise.all(
+    i18n.locales.map(async (locale) => {
+      const localizationDir = path.resolve(
+        siteDir,
+        i18n.path,
+        i18n.localeConfigs[locale]!.path,
+      );
+      // Copy docs files.
+      const docsDir =
+        locale === i18n.defaultLocale
+          ? path.resolve(siteDir, docsPath)
+          : getDocsDirPathLocalized({
+              localizationDir,
+              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({
+              localizationDir,
+              pluginId,
+              versionName: version,
+            });
+      await fs.copy(docsDir, newVersionDir);
+    }),
+  );
+
+  await createVersionedSidebarFile({
+    siteDir,
+    pluginId,
+    version,
+    sidebarPath,
+  });
 
   // Update versions.json file.
   versions.unshift(version);
-  fs.ensureDirSync(path.dirname(versionsJSONFile));
-  fs.writeFileSync(versionsJSONFile, `${JSON.stringify(versions, null, 2)}\n`);
+  await fs.outputFile(
+    getVersionsFilePath(siteDir, pluginId),
+    `${JSON.stringify(versions, null, 2)}\n`,
+  );
 
-  console.log(`${pluginIdLogPrefix}Version ${version} created!`);
+  logger.success`name=${pluginIdLogPrefix}: version name=${version} created!`;
 }

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]}
@@ -57,8 +45,8 @@ 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,
+      `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(
+        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,32 +117,15 @@ export const getActiveDocContext = (
     activeDoc,
     alternateDocVersions: alternateVersionDocs,
   };
-};
-
-export type DocVersionSuggestions = {
-  // suggest the same doc, in latest version (if exist)
-  latestDocSuggestion?: GlobalDoc;
-  // suggest the latest version
-  latestVersionSuggestion?: GlobalVersion;
-};
+}
 
-export const getDocVersionSuggestions = (
+export function getDocVersionSuggestions(
   data: GlobalPluginData,
   pathname: string,
-): DocVersionSuggestions => {
+): DocVersionSuggestions {
   const latestVersion = getLatestVersion(data);
   const activeDocContext = getActiveDocContext(data, pathname);
-
-  // We only suggest another doc/version if user is not using the latest version
-  const isNotOnLatestVersion = activeDocContext.activeVersion !== latestVersion;
-
-  const latestDocSuggestion: GlobalDoc | undefined = isNotOnLatestVersion
-    ? activeDocContext?.alternateDocVersions[latestVersion.name]
-    : undefined;
-
-  const latestVersionSuggestion = isNotOnLatestVersion
-    ? latestVersion
-    : undefined;
-
-  return {latestDocSuggestion, latestVersionSuggestion};
-};
+  const latestDocSuggestion: GlobalDoc | undefined =
+    activeDocContext.alternateDocVersions[latestVersion.name];
+  return {latestDocSuggestion, latestVersionSuggestion: latestVersion};
+}

package/src/client/index.ts

@@ -0,0 +1,158 @@
+/**
+ * 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 {UseDataOptions} from '@docusaurus/types';
+
+export type ActivePlugin = {
+  pluginId: string;
+  pluginData: GlobalPluginData;
+};
+export type ActiveDocContext = {
+  activeVersion?: GlobalVersion;
+  activeDoc?: GlobalDoc;
+  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;
+};
+
+export type GlobalVersion = {
+  name: string;
+  label: string;
+  isLast: boolean;
+  path: string;
+  /** The doc with `slug: /`, or first doc in first sidebar */
+  mainDocId: string;
+  docs: GlobalDoc[];
+  /** Unversioned IDs. In development, this list is empty. */
+  draftIds: string[];
+  sidebars?: {[sidebarId: string]: GlobalSidebar};
+};
+
+export type GlobalSidebar = {
+  link?: {
+    label: string;
+    path: string;
+  };
+  // ... we may add other things here later
+};
+export type GlobalPluginData = {
+  path: string;
+  versions: GlobalVersion[];
+  breadcrumbs: boolean;
+};
+export type DocVersionSuggestions = {
+  /** Suggest the latest version */
+  latestVersionSuggestion: GlobalVersion;
+  /** Suggest the same doc, in latest version (if one exists) */
+  latestDocSuggestion?: GlobalDoc;
+};
+
+// 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,
+  };
+}
+
+/** Versions are returned ordered (most recent first). */
+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);
+}
+
+/**
+ * Returns `undefined` on doc-unrelated pages, because there's no version
+ * currently considered as active.
+ */
+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);
+}
+/**
+ * Useful to say "hey, you are not on the latest docs version, please switch"
+ */
+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';