@docusaurus/plugin-content-docs 2.0.0-beta.8bda3b2db → 2.0.0-beta.9

package/src/sidebars/validation.ts

@@ -0,0 +1,124 @@
+/**
+ * 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 {Joi, URISchema} from '@docusaurus/utils-validation';
+import {
+  SidebarItemConfig,
+  SidebarCategoriesShorthand,
+  SidebarItemBase,
+  SidebarItemAutogenerated,
+  SidebarItemDoc,
+  SidebarItemLink,
+  SidebarItemCategoryConfig,
+  SidebarsConfig,
+  isCategoriesShorthand,
+} from './types';
+
+const sidebarItemBaseSchema = Joi.object<SidebarItemBase>({
+  className: Joi.string(),
+  customProps: Joi.object().unknown(),
+});
+
+const sidebarItemAutogeneratedSchema =
+  sidebarItemBaseSchema.append<SidebarItemAutogenerated>({
+    type: 'autogenerated',
+    dirName: Joi.string()
+      .required()
+      .pattern(/^[^/](.*[^/])?$/)
+      .message(
+        '"dirName" must be a dir path relative to the docs folder root, and should not start or end with slash',
+      ),
+  });
+
+const sidebarItemDocSchema = sidebarItemBaseSchema.append<SidebarItemDoc>({
+  type: Joi.string().valid('doc', 'ref').required(),
+  id: Joi.string().required(),
+  label: Joi.string(),
+});
+
+const sidebarItemLinkSchema = sidebarItemBaseSchema.append<SidebarItemLink>({
+  type: 'link',
+  href: URISchema.required(),
+  label: Joi.string()
+    .required()
+    .messages({'any.unknown': '"label" must be a string'}),
+});
+
+const sidebarItemCategorySchema =
+  sidebarItemBaseSchema.append<SidebarItemCategoryConfig>({
+    type: 'category',
+    label: Joi.string()
+      .required()
+      .messages({'any.unknown': '"label" must be a string'}),
+    // TODO: Joi doesn't allow mutual recursion. See https://github.com/sideway/joi/issues/2611
+    items: Joi.array()
+      .required()
+      .messages({'any.unknown': '"items" must be an array'}), // .items(Joi.link('#sidebarItemSchema')),
+    collapsed: Joi.boolean().messages({
+      'any.unknown': '"collapsed" must be a boolean',
+    }),
+    collapsible: Joi.boolean().messages({
+      'any.unknown': '"collapsible" must be a boolean',
+    }),
+  });
+
+const sidebarItemSchema: Joi.Schema<SidebarItemConfig> = Joi.object()
+  .when('.type', {
+    switch: [
+      {is: 'link', then: sidebarItemLinkSchema},
+      {
+        is: Joi.string().valid('doc', 'ref').required(),
+        then: sidebarItemDocSchema,
+      },
+      {is: 'autogenerated', then: sidebarItemAutogeneratedSchema},
+      {is: 'category', then: sidebarItemCategorySchema},
+      {
+        is: 'subcategory',
+        then: Joi.forbidden().messages({
+          'any.unknown':
+            'Docusaurus v2: "subcategory" has been renamed as "category".',
+        }),
+      },
+      {
+        is: Joi.string().required(),
+        then: Joi.forbidden().messages({
+          'any.unknown': 'Unknown sidebar item type "{.type}".',
+        }),
+      },
+    ],
+  })
+  .id('sidebarItemSchema');
+
+function validateSidebarItem(item: unknown): asserts item is SidebarItemConfig {
+  if (typeof item === 'string') {
+    return;
+  }
+  // TODO: remove once with proper Joi support
+  // Because we can't use Joi to validate nested items (see above), we do it manually
+  if (isCategoriesShorthand(item as SidebarItemConfig)) {
+    Object.values(item as SidebarCategoriesShorthand).forEach((category) =>
+      category.forEach(validateSidebarItem),
+    );
+  } else {
+    Joi.assert(item, sidebarItemSchema);
+    if ((item as SidebarItemCategoryConfig).type === 'category') {
+      (item as SidebarItemCategoryConfig).items.forEach(validateSidebarItem);
+    }
+  }
+}
+
+export function validateSidebars(
+  sidebars: unknown,
+): asserts sidebars is SidebarsConfig {
+  Object.values(sidebars as SidebarsConfig).forEach((sidebar) => {
+    if (Array.isArray(sidebar)) {
+      sidebar.forEach(validateSidebarItem);
+    } else {
+      validateSidebarItem(sidebar);
+    }
+  });
+}

package/src/tags.ts

@@ -0,0 +1,21 @@
+/**
+ * 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 {groupTaggedItems} from '@docusaurus/utils';
+import {VersionTags, DocMetadata} from './types';
+import {mapValues} from 'lodash';
+
+export function getVersionTags(docs: DocMetadata[]): VersionTags {
+  const groups = groupTaggedItems(docs, (doc) => doc.tags);
+  return mapValues(groups, (group) => {
+    return {
+      name: group.tag.label,
+      docIds: group.items.map((item) => item.id),
+      permalink: group.tag.permalink,
+    };
+  });
+}

package/src/theme/hooks/useDocs.ts

@@ -24,11 +24,15 @@ import {
   GetActivePluginOptions,
 } from '../../client/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
 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;

package/src/translations.ts

@@ -5,20 +5,15 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import {
-  LoadedVersion,
-  Sidebar,
-  LoadedContent,
-  Sidebars,
-  SidebarItem,
-} from './types';
+import type {LoadedVersion, LoadedContent} from './types';
+import type {Sidebar, Sidebars} from './sidebars/types';
 
-import {chain, mapValues, flatten, keyBy} from 'lodash';
+import {chain, mapValues, keyBy} from 'lodash';
 import {
   collectSidebarCategories,
   transformSidebarItems,
   collectSidebarLinks,
-} from './sidebars';
+} from './sidebars/utils';
 import {
   TranslationFileContent,
   TranslationFile,
@@ -131,29 +126,25 @@ function translateSidebar({
   sidebarName: string;
   sidebarsTranslations: TranslationFileContent;
 }): Sidebar {
-  return transformSidebarItems(
-    sidebar,
-    (item: SidebarItem): SidebarItem => {
-      if (item.type === 'category') {
-        return {
-          ...item,
-          label:
-            sidebarsTranslations[
-              `sidebar.${sidebarName}.category.${item.label}`
-            ]?.message ?? item.label,
-        };
-      }
-      if (item.type === 'link') {
-        return {
-          ...item,
-          label:
-            sidebarsTranslations[`sidebar.${sidebarName}.link.${item.label}`]
-              ?.message ?? item.label,
-        };
-      }
-      return item;
-    },
-  );
+  return transformSidebarItems(sidebar, (item) => {
+    if (item.type === 'category') {
+      return {
+        ...item,
+        label:
+          sidebarsTranslations[`sidebar.${sidebarName}.category.${item.label}`]
+            ?.message ?? item.label,
+      };
+    }
+    if (item.type === 'link') {
+      return {
+        ...item,
+        label:
+          sidebarsTranslations[`sidebar.${sidebarName}.link.${item.label}`]
+            ?.message ?? item.label,
+      };
+    }
+    return item;
+  });
 }
 
 function getSidebarsTranslations(
@@ -193,9 +184,8 @@ function getVersionTranslationFiles(version: LoadedVersion): TranslationFiles {
     },
   };
 
-  const sidebarsTranslations: TranslationFileContent = getSidebarsTranslations(
-    version,
-  );
+  const sidebarsTranslations: TranslationFileContent =
+    getSidebarsTranslations(version);
 
   // const docsTranslations: TranslationFileContent = getDocsTranslations(version);
 
@@ -227,7 +217,7 @@ function translateVersion(
 function getVersionsTranslationFiles(
   versions: LoadedVersion[],
 ): TranslationFiles {
-  return flatten(versions.map(getVersionTranslationFiles));
+  return versions.flatMap(getVersionTranslationFiles);
 }
 function translateVersions(
   versions: LoadedVersion[],

package/src/types.ts

@@ -5,14 +5,15 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-// eslint-disable-next-line spaced-comment
 /// <reference types="@docusaurus/module-type-aliases" />
 
 import type {RemarkAndRehypePluginOptions} from '@docusaurus/mdx-loader';
-import {
+import type {Tag, FrontMatterTag} from '@docusaurus/utils';
+import type {
   BrokenMarkdownLink as IBrokenMarkdownLink,
   ContentPaths,
 } from '@docusaurus/utils/lib/markdownLinks';
+import type {SidebarItemsGeneratorOption, Sidebars} from './sidebars/types';
 
 export type DocFile = {
   contentPath: string; // /!\ may be localized
@@ -28,8 +29,12 @@ export type VersionMetadata = ContentPaths & {
   versionName: VersionName; // 1.0.0
   versionLabel: string; // Version 1.0.0
   versionPath: string; // /baseUrl/docs/1.0.0
+  tagsPath: string;
   versionEditUrl?: string | undefined;
   versionEditUrlLocalized?: string | undefined;
+  versionBanner: VersionBanner | null;
+  versionBadge: boolean;
+  versionClassName: string;
   isLast: boolean;
   sidebarFilePath: string | false | undefined; // versioned_sidebars/1.0.0.json
   routePriority: number | undefined; // -1 for the latest docs
@@ -59,9 +64,15 @@ export type PathOptions = {
   sidebarPath?: string | false | undefined;
 };
 
+// TODO support custom version banner? {type: "error", content: "html content"}
+export type VersionBanner = 'unreleased' | 'unmaintained';
+
 export type VersionOptions = {
   path?: string;
   label?: string;
+  banner?: 'none' | VersionBanner;
+  badge?: boolean;
+  className?: string;
 };
 
 export type VersionsOptions = {
@@ -70,111 +81,30 @@ export type VersionsOptions = {
   onlyIncludeVersions?: string[];
 };
 
+export type SidebarOptions = {
+  sidebarCollapsible: boolean;
+  sidebarCollapsed: boolean;
+};
+
 export type PluginOptions = MetadataOptions &
   PathOptions &
   VersionsOptions &
-  RemarkAndRehypePluginOptions & {
+  RemarkAndRehypePluginOptions &
+  SidebarOptions & {
     id: string;
     include: string[];
+    exclude: string[];
     docLayoutComponent: string;
     docItemComponent: string;
+    docTagDocListComponent: string;
+    docTagsListComponent: string;
     admonitions: Record<string, unknown>;
     disableVersioning: boolean;
-    excludeNextVersionDocs?: boolean;
     includeCurrentVersion: boolean;
     sidebarItemsGenerator: SidebarItemsGeneratorOption;
+    tagsBasePath: string;
   };
 
-export type SidebarItemBase = {
-  customProps?: Record<string, unknown>;
-};
-
-export type SidebarItemDoc = SidebarItemBase & {
-  type: 'doc' | 'ref';
-  label?: string;
-  id: string;
-};
-
-export type SidebarItemLink = SidebarItemBase & {
-  type: 'link';
-  href: string;
-  label: string;
-};
-
-export type SidebarItemCategory = SidebarItemBase & {
-  type: 'category';
-  label: string;
-  items: SidebarItem[];
-  collapsed: boolean;
-};
-
-export type UnprocessedSidebarItemAutogenerated = {
-  type: 'autogenerated';
-  dirName: string;
-};
-
-export type UnprocessedSidebarItemCategory = SidebarItemBase & {
-  type: 'category';
-  label: string;
-  items: UnprocessedSidebarItem[];
-  collapsed: boolean;
-};
-
-export type UnprocessedSidebarItem =
-  | SidebarItemDoc
-  | SidebarItemLink
-  | UnprocessedSidebarItemCategory
-  | UnprocessedSidebarItemAutogenerated;
-
-export type UnprocessedSidebar = UnprocessedSidebarItem[];
-export type UnprocessedSidebars = Record<string, UnprocessedSidebar>;
-
-export type SidebarItem =
-  | SidebarItemDoc
-  | SidebarItemLink
-  | SidebarItemCategory;
-
-export type Sidebar = SidebarItem[];
-export type SidebarItemType = SidebarItem['type'];
-export type Sidebars = Record<string, Sidebar>;
-
-// Reduce API surface for options.sidebarItemsGenerator
-// The user-provided generator fn should receive only a subset of metadatas
-// A change to any of these metadatas can be considered as a breaking change
-export type SidebarItemsGeneratorDoc = Pick<
-  DocMetadataBase,
-  'id' | 'frontMatter' | 'source' | 'sourceDirName' | 'sidebarPosition'
->;
-export type SidebarItemsGeneratorVersion = Pick<
-  VersionMetadata,
-  'versionName' | 'contentPath'
->;
-
-export type SidebarItemsGeneratorArgs = {
-  item: UnprocessedSidebarItemAutogenerated;
-  version: SidebarItemsGeneratorVersion;
-  docs: SidebarItemsGeneratorDoc[];
-  numberPrefixParser: NumberPrefixParser;
-};
-export type SidebarItemsGenerator = (
-  generatorArgs: SidebarItemsGeneratorArgs,
-) => Promise<SidebarItem[]>;
-
-// Also inject the default generator to conveniently wrap/enhance/sort the default sidebar gen logic
-// see https://github.com/facebook/docusaurus/issues/4640#issuecomment-822292320
-export type SidebarItemsGeneratorOptionArgs = {
-  defaultSidebarItemsGenerator: SidebarItemsGenerator;
-} & SidebarItemsGeneratorArgs;
-export type SidebarItemsGeneratorOption = (
-  generatorArgs: SidebarItemsGeneratorOptionArgs,
-) => Promise<SidebarItem[]>;
-
-export type OrderMetadata = {
-  previous?: string;
-  next?: string;
-  sidebar?: string;
-};
-
 export type LastUpdateData = {
   lastUpdatedAt?: number;
   formattedLastUpdatedAt?: string;
@@ -182,8 +112,11 @@ export type LastUpdateData = {
 };
 
 export type DocFrontMatter = {
+  // Front matter uses snake case
+  /* eslint-disable camelcase */
   id?: string;
   title?: string;
+  tags?: FrontMatterTag[];
   hide_title?: boolean;
   hide_table_of_contents?: boolean;
   keywords?: string[];
@@ -192,9 +125,15 @@ export type DocFrontMatter = {
   slug?: string;
   sidebar_label?: string;
   sidebar_position?: number;
+  sidebar_class_name?: string;
   pagination_label?: string;
   custom_edit_url?: string | null;
   parse_number_prefixes?: boolean;
+  toc_min_heading_level?: number;
+  toc_max_heading_level?: number;
+  pagination_next?: string | null;
+  pagination_prev?: string | null;
+  /* eslint-enable camelcase */
 };
 
 export type DocMetadataBase = LastUpdateData & {
@@ -208,9 +147,9 @@ export type DocMetadataBase = LastUpdateData & {
   sourceDirName: string; // relative to the docs folder (can be ".")
   slug: string;
   permalink: string;
-  // eslint-disable-next-line camelcase
   sidebarPosition?: number;
   editUrl?: string | null;
+  tags: Tag[];
   frontMatter: DocFrontMatter & Record<string, unknown>;
 };
 
@@ -228,12 +167,21 @@ export type DocMetadata = DocMetadataBase & {
 export type SourceToPermalink = {
   [source: string]: string;
 };
+
+export type VersionTag = {
+  name: string; // normalized name/label of the tag
+  docIds: string[]; // all doc ids having this tag
+  permalink: string; // pathname of the tag
+};
+export type VersionTags = {
+  [key: string]: VersionTag;
+};
+
 export type LoadedVersion = VersionMetadata & {
   versionPath: string;
   mainDocId: string;
   docs: DocMetadata[];
   sidebars: Sidebars;
-  permalinkToSidebar: Record<string, string>;
 };
 
 export type LoadedContent = {
@@ -269,6 +217,7 @@ export type DocsMarkdownOption = {
   onBrokenMarkdownLink: (brokenMarkdownLink: BrokenMarkdownLink) => void;
 };
 
-export type NumberPrefixParser = (
-  filename: string,
-) => {filename: string; numberPrefix?: number};
+export type NumberPrefixParser = (filename: string) => {
+  filename: string;
+  numberPrefix?: number;
+};

package/src/versions.ts

@@ -9,6 +9,7 @@ import path from 'path';
 import fs from 'fs-extra';
 import {
   PluginOptions,
+  VersionBanner,
   VersionMetadata,
   VersionOptions,
   VersionsOptions,
@@ -255,14 +256,92 @@ function getVersionEditUrls({
   };
 }
 
+function getDefaultVersionBanner({
+  versionName,
+  versionNames,
+  lastVersionName,
+}: {
+  versionName: string;
+  versionNames: string[];
+  lastVersionName: string;
+}): VersionBanner | null {
+  // Current version: good, no banner
+  if (versionName === lastVersionName) {
+    return null;
+  }
+  // Upcoming versions: unreleased banner
+  else if (
+    versionNames.indexOf(versionName) < versionNames.indexOf(lastVersionName)
+  ) {
+    return 'unreleased';
+  }
+  // Older versions: display unmaintained banner
+  else {
+    return 'unmaintained';
+  }
+}
+
+function getVersionBanner({
+  versionName,
+  versionNames,
+  lastVersionName,
+  options,
+}: {
+  versionName: string;
+  versionNames: string[];
+  lastVersionName: string;
+  options: Pick<PluginOptions, 'versions'>;
+}): VersionBanner | null {
+  const versionBannerOption = options.versions[versionName]?.banner;
+  if (versionBannerOption) {
+    return versionBannerOption === 'none' ? null : versionBannerOption;
+  }
+  return getDefaultVersionBanner({
+    versionName,
+    versionNames,
+    lastVersionName,
+  });
+}
+
+function getVersionBadge({
+  versionName,
+  versionNames,
+  options,
+}: {
+  versionName: string;
+  versionNames: string[];
+  options: Pick<PluginOptions, 'versions'>;
+}): boolean {
+  const versionBadgeOption = options.versions[versionName]?.badge;
+  // If site is not versioned or only one version is included
+  // we don't show the version badge by default
+  // See https://github.com/facebook/docusaurus/issues/3362
+  const versionBadgeDefault = versionNames.length !== 1;
+  return versionBadgeOption ?? versionBadgeDefault;
+}
+
+function getVersionClassName({
+  versionName,
+  options,
+}: {
+  versionName: string;
+  options: Pick<PluginOptions, 'versions'>;
+}): string {
+  const versionClassNameOption = options.versions[versionName]?.className;
+  const versionClassNameDefault = `docs-version-${versionName}`;
+  return versionClassNameOption ?? versionClassNameDefault;
+}
+
 function createVersionMetadata({
   versionName,
-  isLast,
+  versionNames,
+  lastVersionName,
   context,
   options,
 }: {
   versionName: string;
-  isLast: boolean;
+  versionNames: string[];
+  lastVersionName: string;
   context: Pick<LoadContext, 'siteDir' | 'baseUrl' | 'i18n'>;
   options: Pick<
     PluginOptions,
@@ -270,29 +349,27 @@ function createVersionMetadata({
     | 'path'
     | 'sidebarPath'
     | 'routeBasePath'
+    | 'tagsBasePath'
     | 'versions'
     | 'editUrl'
     | 'editCurrentVersion'
   >;
 }): VersionMetadata {
-  const {
-    sidebarFilePath,
-    contentPath,
-    contentPathLocalized,
-  } = getVersionMetadataPaths({
-    versionName,
-    context,
-    options,
-  });
+  const {sidebarFilePath, contentPath, contentPathLocalized} =
+    getVersionMetadataPaths({versionName, context, options});
+
+  const isLast = versionName === lastVersionName;
 
   // retro-compatible values
   const defaultVersionLabel =
     versionName === CURRENT_VERSION_NAME ? 'Next' : versionName;
-  const defaultVersionPathPart = isLast
-    ? ''
-    : versionName === CURRENT_VERSION_NAME
-    ? 'next'
-    : versionName;
+  function getDefaultVersionPathPart() {
+    if (isLast) {
+      return '';
+    }
+    return versionName === CURRENT_VERSION_NAME ? 'next' : versionName;
+  }
+  const defaultVersionPathPart = getDefaultVersionPathPart();
 
   const versionOptions: VersionOptions = options.versions[versionName] ?? {};
 
@@ -315,12 +392,25 @@ function createVersionMetadata({
   // Because /docs/:route` should always be after `/docs/versionName/:route`.
   const routePriority = versionPathPart === '' ? -1 : undefined;
 
+  // the path that will be used to refer the docs tags
+  // example below will be using /docs/tags
+  const tagsPath = normalizeUrl([versionPath, options.tagsBasePath]);
+
   return {
     versionName,
     versionLabel,
     versionPath,
+    tagsPath,
     versionEditUrl: versionEditUrls?.versionEditUrl,
     versionEditUrlLocalized: versionEditUrls?.versionEditUrlLocalized,
+    versionBanner: getVersionBanner({
+      versionName,
+      versionNames,
+      lastVersionName,
+      options,
+    }),
+    versionBadge: getVersionBadge({versionName, versionNames, options}),
+    versionClassName: getVersionClassName({versionName, options}),
     isLast,
     routePriority,
     sidebarFilePath,
@@ -465,6 +555,7 @@ export function readVersionsMetadata({
     | 'path'
     | 'sidebarPath'
     | 'routeBasePath'
+    | 'tagsBasePath'
     | 'includeCurrentVersion'
     | 'disableVersioning'
     | 'lastVersion'
@@ -486,7 +577,8 @@ export function readVersionsMetadata({
   const versionsMetadata = versionNames.map((versionName) =>
     createVersionMetadata({
       versionName,
-      isLast: versionName === lastVersionName,
+      versionNames,
+      lastVersionName,
       context,
       options,
     }),