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

package/src/sidebars/index.ts

@@ -0,0 +1,84 @@
+/**
+ * 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 fs from 'fs-extra';
+import importFresh from 'import-fresh';
+import type {SidebarsConfig, Sidebars, NormalizedSidebars} from './types';
+import type {PluginOptions} from '../types';
+import {validateSidebars} from './validation';
+import {normalizeSidebars} from './normalization';
+import {processSidebars, SidebarProcessorProps} from './processor';
+import path from 'path';
+
+export const DefaultSidebars: SidebarsConfig = {
+  defaultSidebar: [
+    {
+      type: 'autogenerated',
+      dirName: '.',
+    },
+  ],
+};
+
+export const DisabledSidebars: SidebarsConfig = {};
+
+// If a path is provided, make it absolute
+// use this before loadSidebars()
+export function resolveSidebarPathOption(
+  siteDir: string,
+  sidebarPathOption: PluginOptions['sidebarPath'],
+): PluginOptions['sidebarPath'] {
+  return sidebarPathOption
+    ? path.resolve(siteDir, sidebarPathOption)
+    : sidebarPathOption;
+}
+
+function loadSidebarFile(
+  sidebarFilePath: string | false | undefined,
+): SidebarsConfig {
+  // false => no sidebars
+  if (sidebarFilePath === false) {
+    return DisabledSidebars;
+  }
+
+  // undefined => defaults to autogenerated sidebars
+  if (typeof sidebarFilePath === 'undefined') {
+    return DefaultSidebars;
+  }
+
+  // Non-existent sidebars file: no sidebars
+  // Note: this edge case can happen on versioned docs, not current version
+  // We avoid creating empty versioned sidebars file with the CLI
+  if (!fs.existsSync(sidebarFilePath)) {
+    return DisabledSidebars;
+  }
+
+  // We don't want sidebars to be cached because of hot reloading.
+  return importFresh(sidebarFilePath);
+}
+
+export function loadUnprocessedSidebars(
+  sidebarFilePath: string | false | undefined,
+  options: SidebarProcessorProps['options'],
+): NormalizedSidebars {
+  const sidebarsConfig = loadSidebarFile(sidebarFilePath);
+  validateSidebars(sidebarsConfig);
+
+  const normalizedSidebars = normalizeSidebars(sidebarsConfig, options);
+  return normalizedSidebars;
+}
+
+// Note: sidebarFilePath must be absolute, use resolveSidebarPathOption
+export async function loadSidebars(
+  sidebarFilePath: string | false | undefined,
+  options: SidebarProcessorProps,
+): Promise<Sidebars> {
+  const unprocessedSidebars = loadUnprocessedSidebars(
+    sidebarFilePath,
+    options.options,
+  );
+  return processSidebars(unprocessedSidebars, options);
+}

package/src/sidebars/normalization.ts

@@ -0,0 +1,88 @@
+/**
+ * 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 type {SidebarOptions} from '../types';
+import {
+  NormalizedSidebarItem,
+  NormalizedSidebar,
+  NormalizedSidebars,
+  SidebarCategoriesShorthand,
+  SidebarItemCategoryConfig,
+  SidebarItemConfig,
+  SidebarConfig,
+  SidebarsConfig,
+  isCategoriesShorthand,
+} from './types';
+import {mapValues} from 'lodash';
+
+function normalizeCategoriesShorthand(
+  sidebar: SidebarCategoriesShorthand,
+  options: SidebarOptions,
+): SidebarItemCategoryConfig[] {
+  return Object.entries(sidebar).map(([label, items]) => ({
+    type: 'category',
+    collapsed: options.sidebarCollapsed,
+    collapsible: options.sidebarCollapsible,
+    label,
+    items,
+  }));
+}
+
+/**
+ * Normalizes recursively item and all its children. Ensures that at the end
+ * each item will be an object with the corresponding type.
+ */
+function normalizeItem(
+  item: SidebarItemConfig,
+  options: SidebarOptions,
+): NormalizedSidebarItem[] {
+  if (typeof item === 'string') {
+    return [
+      {
+        type: 'doc',
+        id: item,
+      },
+    ];
+  }
+  if (isCategoriesShorthand(item)) {
+    return normalizeCategoriesShorthand(item, options).flatMap((subitem) =>
+      normalizeItem(subitem, options),
+    );
+  }
+  return item.type === 'category'
+    ? [
+        {
+          ...item,
+          items: item.items.flatMap((subItem) =>
+            normalizeItem(subItem, options),
+          ),
+          collapsible: item.collapsible ?? options.sidebarCollapsible,
+          collapsed: item.collapsed ?? options.sidebarCollapsed,
+        },
+      ]
+    : [item];
+}
+
+function normalizeSidebar(
+  sidebar: SidebarConfig,
+  options: SidebarOptions,
+): NormalizedSidebar {
+  const normalizedSidebar = Array.isArray(sidebar)
+    ? sidebar
+    : normalizeCategoriesShorthand(sidebar, options);
+
+  return normalizedSidebar.flatMap((subitem) =>
+    normalizeItem(subitem, options),
+  );
+}
+
+export function normalizeSidebars(
+  sidebars: SidebarsConfig,
+  options: SidebarOptions,
+): NormalizedSidebars {
+  return mapValues(sidebars, (subitem) => normalizeSidebar(subitem, options));
+}

package/src/sidebars/processor.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 type {
+  NumberPrefixParser,
+  DocMetadataBase,
+  VersionMetadata,
+  SidebarOptions,
+} from '../types';
+import type {
+  Sidebars,
+  Sidebar,
+  SidebarItem,
+  NormalizedSidebarItem,
+  NormalizedSidebar,
+  NormalizedSidebars,
+  SidebarItemsGeneratorOption,
+  SidebarItemsGeneratorDoc,
+  SidebarItemsGeneratorVersion,
+} from './types';
+import {transformSidebarItems} from './utils';
+import {DefaultSidebarItemsGenerator} from './generator';
+import {mapValues, memoize, pick} from 'lodash';
+import combinePromises from 'combine-promises';
+
+export type SidebarProcessorProps = {
+  sidebarItemsGenerator: SidebarItemsGeneratorOption;
+  numberPrefixParser: NumberPrefixParser;
+  docs: DocMetadataBase[];
+  version: VersionMetadata;
+  options: SidebarOptions;
+};
+
+function toSidebarItemsGeneratorDoc(
+  doc: DocMetadataBase,
+): SidebarItemsGeneratorDoc {
+  return pick(doc, [
+    'id',
+    'frontMatter',
+    'source',
+    'sourceDirName',
+    'sidebarPosition',
+  ]);
+}
+
+function toSidebarItemsGeneratorVersion(
+  version: VersionMetadata,
+): SidebarItemsGeneratorVersion {
+  return pick(version, ['versionName', 'contentPath']);
+}
+
+// Handle the generation of autogenerated sidebar items and other post-processing checks
+async function processSidebar(
+  unprocessedSidebar: NormalizedSidebar,
+  {
+    sidebarItemsGenerator,
+    numberPrefixParser,
+    docs,
+    version,
+    options,
+  }: SidebarProcessorProps,
+): Promise<Sidebar> {
+  // Just a minor lazy transformation optimization
+  const getSidebarItemsGeneratorDocsAndVersion = memoize(() => ({
+    docs: docs.map(toSidebarItemsGeneratorDoc),
+    version: toSidebarItemsGeneratorVersion(version),
+  }));
+
+  async function handleAutoGeneratedItems(
+    item: NormalizedSidebarItem,
+  ): Promise<SidebarItem[]> {
+    if (item.type === 'category') {
+      return [
+        {
+          ...item,
+          items: (
+            await Promise.all(item.items.map(handleAutoGeneratedItems))
+          ).flat(),
+        },
+      ];
+    }
+    if (item.type === 'autogenerated') {
+      return sidebarItemsGenerator({
+        item,
+        numberPrefixParser,
+        defaultSidebarItemsGenerator: DefaultSidebarItemsGenerator,
+        ...getSidebarItemsGeneratorDocsAndVersion(),
+        options,
+      });
+    }
+    return [item];
+  }
+
+  const processedSidebar = (
+    await Promise.all(unprocessedSidebar.map(handleAutoGeneratedItems))
+  ).flat();
+
+  const fixSidebarItemInconsistencies = (item: SidebarItem): SidebarItem => {
+    // A non-collapsible category can't be collapsed!
+    if (item.type === 'category' && !item.collapsible && item.collapsed) {
+      return {
+        ...item,
+        collapsed: false,
+      };
+    }
+    return item;
+  };
+  return transformSidebarItems(processedSidebar, fixSidebarItemInconsistencies);
+}
+
+export async function processSidebars(
+  unprocessedSidebars: NormalizedSidebars,
+  props: SidebarProcessorProps,
+): Promise<Sidebars> {
+  return combinePromises(
+    mapValues(unprocessedSidebars, (unprocessedSidebar) =>
+      processSidebar(unprocessedSidebar, props),
+    ),
+  );
+}

package/src/sidebars/types.ts

@@ -0,0 +1,156 @@
+/**
+ * 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 {Optional} from 'utility-types';
+import type {
+  DocMetadataBase,
+  VersionMetadata,
+  NumberPrefixParser,
+  SidebarOptions,
+} from '../types';
+
+// Makes all properties visible when hovering over the type
+type Expand<T extends Record<string, unknown>> = {[P in keyof T]: T[P]};
+
+export type SidebarItemBase = {
+  className?: string;
+  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 SidebarItemAutogenerated = SidebarItemBase & {
+  type: 'autogenerated';
+  dirName: string;
+};
+
+type SidebarItemCategoryBase = SidebarItemBase & {
+  type: 'category';
+  label: string;
+  collapsed: boolean;
+  collapsible: boolean;
+};
+
+// The user-given configuration in sidebars.js, before normalization
+export type SidebarItemCategoryConfig = Expand<
+  Optional<SidebarItemCategoryBase, 'collapsed' | 'collapsible'> & {
+    items: SidebarItemConfig[];
+  }
+>;
+
+export type SidebarCategoriesShorthand = {
+  [sidebarCategory: string]: SidebarItemConfig[];
+};
+
+export function isCategoriesShorthand(
+  item: SidebarItemConfig,
+): item is SidebarCategoriesShorthand {
+  return typeof item !== 'string' && !item.type;
+}
+
+export type SidebarItemConfig =
+  | SidebarItemDoc
+  | SidebarItemLink
+  | SidebarItemAutogenerated
+  | SidebarItemCategoryConfig
+  | string
+  | SidebarCategoriesShorthand;
+
+export type SidebarConfig = SidebarCategoriesShorthand | SidebarItemConfig[];
+export type SidebarsConfig = {
+  [sidebarId: string]: SidebarConfig;
+};
+
+// Normalized but still has 'autogenerated', which will be handled in processing
+export type NormalizedSidebarItemCategory = Expand<
+  SidebarItemCategoryBase & {
+    items: NormalizedSidebarItem[];
+  }
+>;
+
+export type NormalizedSidebarItem =
+  | SidebarItemDoc
+  | SidebarItemLink
+  | NormalizedSidebarItemCategory
+  | SidebarItemAutogenerated;
+
+export type NormalizedSidebar = NormalizedSidebarItem[];
+export type NormalizedSidebars = {
+  [sidebarId: string]: NormalizedSidebar;
+};
+
+export type SidebarItemCategory = Expand<
+  SidebarItemCategoryBase & {
+    items: SidebarItem[];
+  }
+>;
+
+export type SidebarItem =
+  | SidebarItemDoc
+  | SidebarItemLink
+  | SidebarItemCategory;
+
+export type Sidebar = SidebarItem[];
+export type SidebarItemType = SidebarItem['type'];
+export type Sidebars = {
+  [sidebarId: string]: Sidebar;
+};
+
+// Doc links have been resolved to URLs, ready to be passed to the theme
+export type PropSidebarItemCategory = Expand<
+  SidebarItemCategoryBase & {
+    items: PropSidebarItem[];
+  }
+>;
+
+export type PropSidebarItem = SidebarItemLink | PropSidebarItemCategory;
+export type PropSidebar = PropSidebarItem[];
+export type PropSidebars = {
+  [sidebarId: string]: PropSidebar;
+};
+
+// 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: SidebarItemAutogenerated;
+  version: SidebarItemsGeneratorVersion;
+  docs: SidebarItemsGeneratorDoc[];
+  numberPrefixParser: NumberPrefixParser;
+  options: SidebarOptions;
+};
+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[]>;

package/src/sidebars/utils.ts

@@ -0,0 +1,146 @@
+/**
+ * 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 type {
+  Sidebars,
+  Sidebar,
+  SidebarItem,
+  SidebarItemCategory,
+  SidebarItemLink,
+  SidebarItemDoc,
+  SidebarItemType,
+} from './types';
+import {mapValues, difference} from 'lodash';
+import {getElementsAround, toMessageRelativeFilePath} from '@docusaurus/utils';
+
+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);
+}
+
+function collectSidebarItemsOfType<
+  Type extends SidebarItemType,
+  Item extends SidebarItem & {type: SidebarItemType},
+>(type: Type, sidebar: Sidebar): Item[] {
+  function collectRecursive(item: SidebarItem): Item[] {
+    const currentItemsCollected: Item[] =
+      item.type === type ? [item as Item] : [];
+
+    const childItemsCollected: Item[] =
+      item.type === 'category' ? item.items.flatMap(collectRecursive) : [];
+
+    return [...currentItemsCollected, ...childItemsCollected];
+  }
+
+  return sidebar.flatMap(collectRecursive);
+}
+
+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);
+}
+
+export function collectSidebarsDocIds(
+  sidebars: Sidebars,
+): Record<string, string[]> {
+  return mapValues(sidebars, (sidebar) => {
+    return collectSidebarDocItems(sidebar).map((docItem) => docItem.id);
+  });
+}
+
+export function createSidebarsUtils(sidebars: Sidebars): {
+  getFirstDocIdOfFirstSidebar: () => string | undefined;
+  getSidebarNameByDocId: (docId: string) => string | undefined;
+  getDocNavigation: (docId: string) => {
+    sidebarName: string | undefined;
+    previousId: string | undefined;
+    nextId: string | undefined;
+  };
+  checkSidebarsDocIds: (validDocIds: string[], sidebarFilePath: string) => void;
+} {
+  const sidebarNameToDocIds = collectSidebarsDocIds(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 getDocNavigation(docId: string): {
+    sidebarName: string | undefined;
+    previousId: string | undefined;
+    nextId: string | undefined;
+  } {
+    const sidebarName = getSidebarNameByDocId(docId);
+    if (sidebarName) {
+      const docIds = sidebarNameToDocIds[sidebarName];
+      const currentIndex = docIds.indexOf(docId);
+      const {previous, next} = getElementsAround(docIds, currentIndex);
+      return {
+        sidebarName,
+        previousId: previous,
+        nextId: next,
+      };
+    } else {
+      return {
+        sidebarName: undefined,
+        previousId: undefined,
+        nextId: undefined,
+      };
+    }
+  }
+
+  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:
+- ${validDocIds.sort().join('\n- ')}`,
+      );
+    }
+  }
+
+  return {
+    getFirstDocIdOfFirstSidebar,
+    getSidebarNameByDocId,
+    getDocNavigation,
+    checkSidebarsDocIds,
+  };
+}