@docusaurus/plugin-content-docs 2.0.0-beta.1ec2c95e3 → 2.0.0-beta.21

package/src/sidebars/utils.ts

@@ -0,0 +1,390 @@
+/**
+ * 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 _ from 'lodash';
+import {toMessageRelativeFilePath} from '@docusaurus/utils';
+import type {
+  Sidebars,
+  Sidebar,
+  SidebarItem,
+  SidebarItemCategory,
+  SidebarItemLink,
+  SidebarItemDoc,
+  SidebarItemType,
+  SidebarCategoriesShorthand,
+  SidebarItemConfig,
+  SidebarItemCategoryWithGeneratedIndex,
+  SidebarNavigationItem,
+} from './types';
+import type {
+  DocMetadataBase,
+  PropNavigationLink,
+} from '@docusaurus/plugin-content-docs';
+
+export function isCategoriesShorthand(
+  item: SidebarItemConfig,
+): item is SidebarCategoriesShorthand {
+  return typeof item === 'object' && !item.type;
+}
+
+export function transformSidebarItems(
+  sidebar: Sidebar,
+  updateFn: (item: SidebarItem) => SidebarItem,
+): Sidebar {
+  function transformRecursive(item: SidebarItem): SidebarItem {
+    if (item.type === 'category') {
+      return updateFn({
+        ...item,
+        items: item.items.map(transformRecursive),
+      });
+    }
+    return updateFn(item);
+  }
+  return sidebar.map(transformRecursive);
+}
+
+/**
+ * Flatten sidebar items into a single flat array (containing categories/docs on
+ * the same level). Order matters (useful for next/prev nav), top categories
+ * appear before their child elements
+ */
+function flattenSidebarItems(items: SidebarItem[]): SidebarItem[] {
+  function flattenRecursive(item: SidebarItem): SidebarItem[] {
+    return item.type === 'category'
+      ? [item, ...item.items.flatMap(flattenRecursive)]
+      : [item];
+  }
+  return items.flatMap(flattenRecursive);
+}
+
+function collectSidebarItemsOfType<
+  Type extends SidebarItemType,
+  Item extends SidebarItem & {type: SidebarItemType},
+>(type: Type, sidebar: Sidebar): Item[] {
+  return flattenSidebarItems(sidebar).filter(
+    (item) => item.type === type,
+  ) as Item[];
+}
+
+export function collectSidebarDocItems(sidebar: Sidebar): SidebarItemDoc[] {
+  return collectSidebarItemsOfType('doc', sidebar);
+}
+export function collectSidebarCategories(
+  sidebar: Sidebar,
+): SidebarItemCategory[] {
+  return collectSidebarItemsOfType('category', sidebar);
+}
+export function collectSidebarLinks(sidebar: Sidebar): SidebarItemLink[] {
+  return collectSidebarItemsOfType('link', sidebar);
+}
+
+// /!\ docId order matters for navigation!
+export function collectSidebarDocIds(sidebar: Sidebar): string[] {
+  return flattenSidebarItems(sidebar).flatMap((item) => {
+    if (item.type === 'category') {
+      return item.link?.type === 'doc' ? [item.link.id] : [];
+    }
+    if (item.type === 'doc') {
+      return [item.id];
+    }
+    return [];
+  });
+}
+
+export function collectSidebarNavigation(
+  sidebar: Sidebar,
+): SidebarNavigationItem[] {
+  return flattenSidebarItems(sidebar).flatMap((item) => {
+    if (item.type === 'category' && item.link) {
+      return [item as SidebarNavigationItem];
+    }
+    if (item.type === 'doc') {
+      return [item];
+    }
+    return [];
+  });
+}
+
+export function collectSidebarsDocIds(sidebars: Sidebars): {
+  [sidebarId: string]: string[];
+} {
+  return _.mapValues(sidebars, collectSidebarDocIds);
+}
+
+export function collectSidebarsNavigations(sidebars: Sidebars): {
+  [sidebarId: string]: SidebarNavigationItem[];
+} {
+  return _.mapValues(sidebars, collectSidebarNavigation);
+}
+
+export type SidebarNavigation = {
+  sidebarName: string | undefined;
+  previous: SidebarNavigationItem | undefined;
+  next: SidebarNavigationItem | undefined;
+};
+
+// A convenient and performant way to query the sidebars content
+export type SidebarsUtils = {
+  sidebars: Sidebars;
+  getFirstDocIdOfFirstSidebar: () => string | undefined;
+  getSidebarNameByDocId: (docId: string) => string | undefined;
+  getDocNavigation: (
+    unversionedId: string,
+    versionedId: string,
+    displayedSidebar: string | null | undefined,
+  ) => SidebarNavigation;
+  getCategoryGeneratedIndexList: () => SidebarItemCategoryWithGeneratedIndex[];
+  getCategoryGeneratedIndexNavigation: (
+    categoryGeneratedIndexPermalink: string,
+  ) => SidebarNavigation;
+  /**
+   * This function may return undefined. This is usually a user mistake, because
+   * it means this sidebar will never be displayed; however, we can still use
+   * `displayed_sidebar` to make it displayed. Pretty weird but valid use-case
+   */
+  getFirstLink: (sidebarId: string) =>
+    | {
+        type: 'doc';
+        id: string;
+        label: string;
+      }
+    | {
+        type: 'generated-index';
+        permalink: string;
+        label: string;
+      }
+    | undefined;
+
+  checkSidebarsDocIds: (validDocIds: string[], sidebarFilePath: string) => void;
+};
+
+export function createSidebarsUtils(sidebars: Sidebars): SidebarsUtils {
+  const sidebarNameToDocIds = collectSidebarsDocIds(sidebars);
+  const sidebarNameToNavigationItems = collectSidebarsNavigations(sidebars);
+
+  // Reverse mapping
+  const docIdToSidebarName = Object.fromEntries(
+    Object.entries(sidebarNameToDocIds).flatMap(([sidebarName, docIds]) =>
+      docIds.map((docId) => [docId, sidebarName]),
+    ),
+  );
+
+  function getFirstDocIdOfFirstSidebar(): string | undefined {
+    return Object.values(sidebarNameToDocIds)[0]?.[0];
+  }
+
+  function getSidebarNameByDocId(docId: string): string | undefined {
+    return docIdToSidebarName[docId];
+  }
+
+  function emptySidebarNavigation(): SidebarNavigation {
+    return {
+      sidebarName: undefined,
+      previous: undefined,
+      next: undefined,
+    };
+  }
+
+  function getDocNavigation(
+    unversionedId: string,
+    versionedId: string,
+    displayedSidebar: string | null | undefined,
+  ): SidebarNavigation {
+    // TODO legacy id retro-compatibility!
+    let docId = unversionedId;
+    let sidebarName =
+      displayedSidebar === undefined
+        ? getSidebarNameByDocId(docId)
+        : displayedSidebar;
+    if (sidebarName === undefined) {
+      docId = versionedId;
+      sidebarName = getSidebarNameByDocId(docId);
+    }
+
+    if (!sidebarName) {
+      return emptySidebarNavigation();
+    }
+    const navigationItems = sidebarNameToNavigationItems[sidebarName];
+    if (!navigationItems) {
+      throw new Error(
+        `Doc with ID ${docId} wants to display sidebar ${sidebarName} but a sidebar with this name doesn't exist`,
+      );
+    }
+    const currentItemIndex = navigationItems.findIndex((item) => {
+      if (item.type === 'doc') {
+        return item.id === docId;
+      }
+      if (item.type === 'category' && item.link.type === 'doc') {
+        return item.link.id === docId;
+      }
+      return false;
+    });
+    if (currentItemIndex === -1) {
+      return {sidebarName, next: undefined, previous: undefined};
+    }
+
+    return {
+      sidebarName,
+      previous: navigationItems[currentItemIndex - 1],
+      next: navigationItems[currentItemIndex + 1],
+    };
+  }
+
+  function getCategoryGeneratedIndexList(): SidebarItemCategoryWithGeneratedIndex[] {
+    return Object.values(sidebarNameToNavigationItems)
+      .flat()
+      .flatMap((item) => {
+        if (item.type === 'category' && item.link.type === 'generated-index') {
+          return [item as SidebarItemCategoryWithGeneratedIndex];
+        }
+        return [];
+      });
+  }
+
+  /**
+   * We identity the category generated index by its permalink (should be
+   * unique). More reliable than using object identity
+   */
+  function getCategoryGeneratedIndexNavigation(
+    categoryGeneratedIndexPermalink: string,
+  ): SidebarNavigation {
+    function isCurrentCategoryGeneratedIndexItem(
+      item: SidebarNavigationItem,
+    ): boolean {
+      return (
+        item.type === 'category' &&
+        item.link.type === 'generated-index' &&
+        item.link.permalink === categoryGeneratedIndexPermalink
+      );
+    }
+
+    const sidebarName = Object.entries(sidebarNameToNavigationItems).find(
+      ([, navigationItems]) =>
+        navigationItems.find(isCurrentCategoryGeneratedIndexItem),
+    )![0];
+    const navigationItems = sidebarNameToNavigationItems[sidebarName]!;
+    const currentItemIndex = navigationItems.findIndex(
+      isCurrentCategoryGeneratedIndexItem,
+    );
+    return {
+      sidebarName,
+      previous: navigationItems[currentItemIndex - 1],
+      next: navigationItems[currentItemIndex + 1],
+    };
+  }
+
+  function checkSidebarsDocIds(validDocIds: string[], sidebarFilePath: string) {
+    const allSidebarDocIds = Object.values(sidebarNameToDocIds).flat();
+    const invalidSidebarDocIds = _.difference(allSidebarDocIds, validDocIds);
+    if (invalidSidebarDocIds.length > 0) {
+      throw new Error(
+        `Invalid sidebar file at "${toMessageRelativeFilePath(
+          sidebarFilePath,
+        )}".
+These sidebar document ids do not exist:
+- ${invalidSidebarDocIds.sort().join('\n- ')}
+
+Available document ids are:
+- ${_.uniq(validDocIds).sort().join('\n- ')}`,
+      );
+    }
+  }
+
+  function getFirstLink(sidebar: Sidebar):
+    | {
+        type: 'doc';
+        id: string;
+        label: string;
+      }
+    | {
+        type: 'generated-index';
+        permalink: string;
+        label: string;
+      }
+    | undefined {
+    for (const item of sidebar) {
+      if (item.type === 'doc') {
+        return {
+          type: 'doc',
+          id: item.id,
+          label: item.label ?? item.id,
+        };
+      } else if (item.type === 'category') {
+        if (item.link?.type === 'doc') {
+          return {
+            type: 'doc',
+            id: item.link.id,
+            label: item.label,
+          };
+        } else if (item.link?.type === 'generated-index') {
+          return {
+            type: 'generated-index',
+            permalink: item.link.permalink,
+            label: item.label,
+          };
+        }
+        const firstSubItem = getFirstLink(item.items);
+        if (firstSubItem) {
+          return firstSubItem;
+        }
+      }
+    }
+    return undefined;
+  }
+
+  return {
+    sidebars,
+    getFirstDocIdOfFirstSidebar,
+    getSidebarNameByDocId,
+    getDocNavigation,
+    getCategoryGeneratedIndexList,
+    getCategoryGeneratedIndexNavigation,
+    checkSidebarsDocIds,
+    getFirstLink: (id) => getFirstLink(sidebars[id]!),
+  };
+}
+
+export function toDocNavigationLink(doc: DocMetadataBase): PropNavigationLink {
+  const {
+    title,
+    permalink,
+    frontMatter: {
+      pagination_label: paginationLabel,
+      sidebar_label: sidebarLabel,
+    },
+  } = doc;
+  return {title: paginationLabel ?? sidebarLabel ?? title, permalink};
+}
+
+export function toNavigationLink(
+  navigationItem: SidebarNavigationItem | undefined,
+  docsById: {[docId: string]: DocMetadataBase},
+): PropNavigationLink | undefined {
+  function getDocById(docId: string) {
+    const doc = docsById[docId];
+    if (!doc) {
+      throw new Error(
+        `Can't create navigation link: no doc found with id=${docId}`,
+      );
+    }
+    return doc;
+  }
+
+  if (!navigationItem) {
+    return undefined;
+  }
+
+  if (navigationItem.type === 'category') {
+    return navigationItem.link.type === 'doc'
+      ? toDocNavigationLink(getDocById(navigationItem.link.id))
+      : {
+          title: navigationItem.label,
+          permalink: navigationItem.link.permalink,
+        };
+  }
+  return toDocNavigationLink(getDocById(navigationItem.id));
+}

package/src/sidebars/validation.ts

@@ -0,0 +1,178 @@
+/**
+ * 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 type {
+  SidebarItemConfig,
+  SidebarItemBase,
+  SidebarItemAutogenerated,
+  SidebarItemDoc,
+  SidebarItemHtml,
+  SidebarItemLink,
+  SidebarItemCategoryConfig,
+  SidebarItemCategoryLink,
+  SidebarItemCategoryLinkDoc,
+  SidebarItemCategoryLinkGeneratedIndex,
+  NormalizedSidebars,
+  NormalizedSidebarItem,
+  NormalizedSidebarItemCategory,
+  CategoryMetadataFile,
+} from './types';
+
+// NOTE: we don't add any default values during validation on purpose!
+// Config types are exposed to users for typechecking and we use the same type
+// in normalization
+
+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 sidebarItemHtmlSchema = sidebarItemBaseSchema.append<SidebarItemHtml>({
+  type: 'html',
+  value: Joi.string().required(),
+  defaultStyle: Joi.boolean(),
+});
+
+const sidebarItemLinkSchema = sidebarItemBaseSchema.append<SidebarItemLink>({
+  type: 'link',
+  href: URISchema.required(),
+  label: Joi.string()
+    .required()
+    .messages({'any.unknown': '"label" must be a string'}),
+});
+
+const sidebarItemCategoryLinkSchema = Joi.object<SidebarItemCategoryLink>()
+  .allow(null)
+  .when('.type', {
+    switch: [
+      {
+        is: 'doc',
+        then: Joi.object<SidebarItemCategoryLinkDoc>({
+          type: 'doc',
+          id: Joi.string().required(),
+        }),
+      },
+      {
+        is: 'generated-index',
+        then: Joi.object<SidebarItemCategoryLinkGeneratedIndex>({
+          type: 'generated-index',
+          slug: Joi.string().optional(),
+          // This one is not in the user config, only in the normalized version
+          // permalink: Joi.string().optional(),
+          title: Joi.string().optional(),
+          description: Joi.string().optional(),
+          image: Joi.string().optional(),
+          keywords: [Joi.string(), Joi.array().items(Joi.string())],
+        }),
+      },
+      {
+        is: Joi.required(),
+        then: Joi.forbidden().messages({
+          'any.unknown': 'Unknown sidebar category link type "{.type}".',
+        }),
+      },
+    ],
+  });
+
+const sidebarItemCategorySchema =
+  sidebarItemBaseSchema.append<SidebarItemCategoryConfig>({
+    type: 'category',
+    label: Joi.string()
+      .required()
+      .messages({'any.unknown': '"label" must be a string'}),
+    items: Joi.array()
+      .required()
+      .messages({'any.unknown': '"items" must be an array'}),
+    // TODO: Joi doesn't allow mutual recursion. See https://github.com/sideway/joi/issues/2611
+    // .items(Joi.link('#sidebarItemSchema')),
+    link: sidebarItemCategoryLinkSchema,
+    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.object<SidebarItemConfig>().when('.type', {
+  switch: [
+    {is: 'link', then: sidebarItemLinkSchema},
+    {
+      is: Joi.string().valid('doc', 'ref').required(),
+      then: sidebarItemDocSchema,
+    },
+    {is: 'html', then: sidebarItemHtmlSchema},
+    {is: 'autogenerated', then: sidebarItemAutogeneratedSchema},
+    {is: 'category', then: sidebarItemCategorySchema},
+    {
+      is: Joi.any().required(),
+      then: Joi.forbidden().messages({
+        'any.unknown': 'Unknown sidebar item type "{.type}".',
+      }),
+    },
+  ],
+});
+// .id('sidebarItemSchema');
+
+function validateSidebarItem(
+  item: unknown,
+): asserts item is NormalizedSidebarItem {
+  // TODO: remove once with proper Joi support
+  // Because we can't use Joi to validate nested items (see above), we do it
+  // manually
+  Joi.assert(item, sidebarItemSchema);
+
+  if ((item as NormalizedSidebarItem).type === 'category') {
+    (item as NormalizedSidebarItemCategory).items.forEach(validateSidebarItem);
+  }
+}
+
+export function validateSidebars(sidebars: {
+  [sidebarId: string]: unknown;
+}): asserts sidebars is NormalizedSidebars {
+  Object.values(sidebars as NormalizedSidebars).forEach((sidebar) => {
+    sidebar.forEach(validateSidebarItem);
+  });
+}
+
+const categoryMetadataFileSchema = Joi.object<CategoryMetadataFile>({
+  label: Joi.string(),
+  position: Joi.number(),
+  collapsed: Joi.boolean(),
+  collapsible: Joi.boolean(),
+  className: Joi.string(),
+  link: sidebarItemCategoryLinkSchema,
+  customProps: Joi.object().unknown(),
+});
+
+export function validateCategoryMetadataFile(
+  unsafeContent: unknown,
+): CategoryMetadataFile {
+  const {error, value} = categoryMetadataFileSchema.validate(unsafeContent);
+  if (error) {
+    throw error;
+  }
+  return value;
+}

package/src/slug.ts

@@ -15,50 +15,69 @@ import {
   DefaultNumberPrefixParser,
   stripPathNumberPrefixes,
 } from './numberPrefix';
-import {NumberPrefixParser} from './types';
+import {isCategoryIndex, toCategoryIndexMatcherParam} from './docs';
+import type {
+  NumberPrefixParser,
+  DocMetadataBase,
+} from '@docusaurus/plugin-content-docs';
 
 export default function getSlug({
   baseID,
-  frontmatterSlug,
-  dirName,
+  frontMatterSlug,
+  source,
+  sourceDirName,
   stripDirNumberPrefixes = true,
   numberPrefixParser = DefaultNumberPrefixParser,
 }: {
   baseID: string;
-  frontmatterSlug?: string;
-  dirName: string;
+  frontMatterSlug?: string;
+  source: DocMetadataBase['source'];
+  sourceDirName: DocMetadataBase['sourceDirName'];
   stripDirNumberPrefixes?: boolean;
   numberPrefixParser?: NumberPrefixParser;
 }): string {
-  const baseSlug = frontmatterSlug || baseID;
-  let slug: string;
-  if (baseSlug.startsWith('/')) {
-    slug = baseSlug;
-  } else {
+  function getDirNameSlug(): string {
     const dirNameStripped = stripDirNumberPrefixes
-      ? stripPathNumberPrefixes(dirName, numberPrefixParser)
-      : dirName;
+      ? stripPathNumberPrefixes(sourceDirName, numberPrefixParser)
+      : sourceDirName;
     const resolveDirname =
-      dirName === '.'
+      sourceDirName === '.'
         ? '/'
         : addLeadingSlash(addTrailingSlash(dirNameStripped));
-    slug = resolvePathname(baseSlug, resolveDirname);
+    return resolveDirname;
   }
 
-  if (!isValidPathname(slug)) {
-    throw new Error(
-      `We couldn't compute a valid slug for document with id "${baseID}" in "${dirName}" directory.
+  function computeSlug(): string {
+    if (frontMatterSlug?.startsWith('/')) {
+      return frontMatterSlug;
+    }
+    const dirNameSlug = getDirNameSlug();
+    if (
+      !frontMatterSlug &&
+      isCategoryIndex(toCategoryIndexMatcherParam({source, sourceDirName}))
+    ) {
+      return dirNameSlug;
+    }
+    const baseSlug = frontMatterSlug ?? baseID;
+    return resolvePathname(baseSlug, getDirNameSlug());
+  }
+
+  function ensureValidSlug(slug: string): string {
+    if (!isValidPathname(slug)) {
+      throw new Error(
+        `We couldn't compute a valid slug for document with ID "${baseID}" in "${sourceDirName}" directory.
 The slug we computed looks invalid: ${slug}.
-Maybe your slug frontmatter is incorrect or you use weird chars in the file path?
-By using the slug frontmatter, you should be able to fix this error, by using the slug of your choice:
+Maybe your slug front matter is incorrect or there are special characters in the file path?
+By using front matter to set a custom slug, you should be able to fix this error:
 
-Example =>
 ---
 slug: /my/customDocPath
 ---
 `,
-    );
+      );
+    }
+    return slug;
   }
 
-  return slug;
+  return ensureValidSlug(computeSlug());
 }

package/src/tags.ts

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