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

package/src/cli.ts

@@ -12,15 +12,15 @@ import {
 } from './versions';
 import fs from 'fs-extra';
 import path from 'path';
-import {
+import type {
   PathOptions,
-  UnprocessedSidebarItem,
-  UnprocessedSidebars,
-} from './types';
-import {loadSidebars} from './sidebars';
-import {DEFAULT_PLUGIN_ID} from '@docusaurus/core/lib/constants';
+  SidebarOptions,
+} from '@docusaurus/plugin-content-docs';
+import {loadSidebarsFileUnsafe, resolveSidebarPathOption} from './sidebars';
+import {DEFAULT_PLUGIN_ID} from '@docusaurus/utils';
+import logger from '@docusaurus/logger';
 
-function createVersionedSidebarFile({
+async function createVersionedSidebarFile({
   siteDir,
   pluginId,
   sidebarPath,
@@ -32,83 +32,57 @@ 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(
+    await fs.ensureDir(path.dirname(newSidebarFile));
+    await fs.writeFile(
       newSidebarFile,
-      `${JSON.stringify(versionedSidebar, null, 2)}\n`,
+      `${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(
+export async function cliDocsVersionCommand(
   version: string | null | undefined,
   siteDir: string,
   pluginId: string,
-  options: PathOptions,
-): void {
+  options: PathOptions & SidebarOptions,
+): 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}] `;
+    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`,
+      `${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 (\\). Try something like: 1.0.0`,
+      `${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 must <= 32 characters. Try something like: 1.0.0`,
+      `${pluginIdLogPrefix}: invalid version tag specified! Length cannot exceed 32 characters. Try something like: 1.0.0.`,
     );
   }
 
@@ -117,27 +91,27 @@ export function cliDocsVersionCommand(
   // 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`,
+      `${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`,
+      `${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'));
+  if (await fs.pathExists(versionsJSONFile)) {
+    versions = JSON.parse(await fs.readFile(versionsJSONFile, 'utf8'));
   }
 
   // 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.`,
     );
   }
 
@@ -145,20 +119,32 @@ export function cliDocsVersionCommand(
 
   // Copy docs files.
   const docsDir = path.join(siteDir, docsPath);
-  if (fs.existsSync(docsDir) && fs.readdirSync(docsDir).length > 0) {
+
+  if (
+    (await fs.pathExists(docsDir)) &&
+    (await fs.readdir(docsDir)).length > 0
+  ) {
     const versionedDir = getVersionedDocsDirPath(siteDir, pluginId);
     const newVersionDir = path.join(versionedDir, `version-${version}`);
-    fs.copySync(docsDir, newVersionDir);
+    await fs.copy(docsDir, newVersionDir);
   } else {
-    throw new Error(`${pluginIdLogPrefix}There is no docs to version !`);
+    throw new Error(`${pluginIdLogPrefix}: there is no docs to version!`);
   }
 
-  createVersionedSidebarFile({siteDir, pluginId, version, sidebarPath});
+  await createVersionedSidebarFile({
+    siteDir,
+    pluginId,
+    version,
+    sidebarPath: resolveSidebarPathOption(siteDir, sidebarPath),
+  });
 
   // Update versions.json file.
   versions.unshift(version);
-  fs.ensureDirSync(path.dirname(versionsJSONFile));
-  fs.writeFileSync(versionsJSONFile, `${JSON.stringify(versions, null, 2)}\n`);
+  await fs.ensureDir(path.dirname(versionsJSONFile));
+  await fs.writeFile(
+    versionsJSONFile,
+    `${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,
+  GetActivePluginOptions,
+  ActivePlugin,
+  ActiveDocContext,
+  DocVersionSuggestions,
+} from '@docusaurus/plugin-content-docs/client';
 
 // 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>,
   pathname: string,
   options: GetActivePluginOptions = {},
 ): ActivePlugin | undefined {
-  const activeEntry = Object.entries(allPluginDatas).find(
-    ([_id, pluginData]) => {
-      return !!matchPath(pathname, {
-        path: pluginData.path,
-        exact: false,
-        strict: false,
-      });
-    },
-  );
+  const activeEntry = Object.entries(allPluginDatas)
+    // 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,7 +45,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(
+      `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)
@@ -68,36 +56,30 @@ 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 = (
   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 = (
@@ -139,30 +121,13 @@ export const getActiveDocContext = (
   };
 };
 
-export type DocVersionSuggestions = {
-  // suggest the same doc, in latest version (if exist)
-  latestDocSuggestion?: GlobalDoc;
-  // suggest the latest version
-  latestVersionSuggestion?: GlobalVersion;
-};
-
 export const getDocVersionSuggestions = (
   data: GlobalPluginData,
   pathname: string,
 ): 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/{theme/hooks/useDocs.ts → client/index.ts}

@@ -6,33 +6,38 @@
  */
 
 import {useLocation} from '@docusaurus/router';
-import useGlobalData, {
-  // useAllPluginInstancesData,
-  usePluginData,
-} from '@docusaurus/useGlobalData';
+import useGlobalData, {usePluginData} from '@docusaurus/useGlobalData';
 
-import {GlobalPluginData, GlobalVersion} from '../../types';
 import {
   getActivePlugin,
   getLatestVersion,
   getActiveVersion,
   getActiveDocContext,
   getDocVersionSuggestions,
+} from './docsClientUtils';
+import type {
+  GlobalPluginData,
+  GlobalVersion,
   ActivePlugin,
   ActiveDocContext,
   DocVersionSuggestions,
   GetActivePluginOptions,
-} from '../../client/docsClientUtils';
+} from '@docusaurus/plugin-content-docs/client';
 
-// 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
+// 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'] ?? {};
+  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 => {

package/src/docFrontMatter.ts

@@ -5,30 +5,17 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-/* eslint-disable camelcase */
-
 import {
-  JoiFrontMatter as Joi, // Custom instance for frontmatter
+  JoiFrontMatter as Joi, // Custom instance for front matter
+  URISchema,
+  FrontMatterTagsSchema,
+  FrontMatterTOCHeadingLevels,
   validateFrontMatter,
 } from '@docusaurus/utils-validation';
-
-export type DocFrontMatter = {
-  id?: string;
-  title?: string;
-  hide_title?: boolean;
-  hide_table_of_contents?: boolean;
-  keywords?: string[];
-  image?: string;
-  description?: string;
-  slug?: string;
-  sidebar_label?: string;
-  sidebar_position?: number;
-  custom_edit_url?: string | null;
-  parse_number_prefixes?: boolean;
-};
+import type {DocFrontMatter} from './types';
 
 // NOTE: we don't add any default value on purpose here
-// We don't want default values to magically appear in doc metadatas and props
+// We don't want default values to magically appear in doc metadata and props
 // While the user did not provide those values explicitly
 // We use default values in code instead
 const DocFrontMatterSchema = Joi.object<DocFrontMatter>({
@@ -37,13 +24,21 @@ const DocFrontMatterSchema = Joi.object<DocFrontMatter>({
   hide_title: Joi.boolean(),
   hide_table_of_contents: Joi.boolean(),
   keywords: Joi.array().items(Joi.string().required()),
-  image: Joi.string().uri({allowRelative: false}),
+  image: URISchema,
   description: Joi.string().allow(''), // see  https://github.com/facebook/docusaurus/issues/4591#issuecomment-822372398
   slug: Joi.string(),
   sidebar_label: Joi.string(),
-  sidebar_position: Joi.number().min(0),
-  custom_edit_url: Joi.string().uri({allowRelative: true}).allow('', null),
+  sidebar_position: Joi.number(),
+  sidebar_class_name: Joi.string(),
+  sidebar_custom_props: Joi.object().unknown(),
+  displayed_sidebar: Joi.string().allow(null),
+  tags: FrontMatterTagsSchema,
+  pagination_label: Joi.string(),
+  custom_edit_url: URISchema.allow('', null),
   parse_number_prefixes: Joi.boolean(),
+  pagination_next: Joi.string().allow(null),
+  pagination_prev: Joi.string().allow(null),
+  ...FrontMatterTOCHeadingLevels,
 }).unknown();
 
 export function validateDocFrontMatter(