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

package/src/sidebars/index.ts

@@ -0,0 +1,118 @@
+/**
+ * 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 path from 'path';
+import _ from 'lodash';
+import logger from '@docusaurus/logger';
+import {Globby} from '@docusaurus/utils';
+import Yaml from 'js-yaml';
+import combinePromises from 'combine-promises';
+import importFresh from 'import-fresh';
+import {validateSidebars, validateCategoryMetadataFile} from './validation';
+import {normalizeSidebars} from './normalization';
+import {processSidebars} from './processor';
+import {postProcessSidebars} from './postProcessor';
+import type {PluginOptions} from '@docusaurus/plugin-content-docs';
+import type {SidebarsConfig, Sidebars, SidebarProcessorParams} from './types';
+
+export const DefaultSidebars: SidebarsConfig = {
+  defaultSidebar: [
+    {
+      type: 'autogenerated',
+      dirName: '.',
+    },
+  ],
+};
+
+export const DisabledSidebars: SidebarsConfig = {};
+
+// If a path is provided, make it absolute
+export function resolveSidebarPathOption(
+  siteDir: string,
+  sidebarPathOption: PluginOptions['sidebarPath'],
+): PluginOptions['sidebarPath'] {
+  return sidebarPathOption
+    ? path.resolve(siteDir, sidebarPathOption)
+    : sidebarPathOption;
+}
+
+async function readCategoriesMetadata(contentPath: string) {
+  const categoryFiles = await Globby('**/_category_.{json,yml,yaml}', {
+    cwd: contentPath,
+  });
+  const categoryToFile = _.groupBy(categoryFiles, path.dirname);
+  return combinePromises(
+    _.mapValues(categoryToFile, async (files, folder) => {
+      const filePath = files[0]!;
+      if (files.length > 1) {
+        logger.warn`There are more than one category metadata files for path=${folder}: ${files.join(
+          ', ',
+        )}. The behavior is undetermined.`;
+      }
+      const content = await fs.readFile(
+        path.join(contentPath, filePath),
+        'utf-8',
+      );
+      try {
+        return validateCategoryMetadataFile(Yaml.load(content));
+      } catch (err) {
+        logger.error`The docs sidebar category metadata file path=${filePath} looks invalid!`;
+        throw err;
+      }
+    }),
+  );
+}
+
+export async function loadSidebarsFileUnsafe(
+  sidebarFilePath: string | false | undefined,
+): Promise<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 (!(await fs.pathExists(sidebarFilePath))) {
+    return DisabledSidebars;
+  }
+
+  // We don't want sidebars to be cached because of hot reloading.
+  return importFresh(sidebarFilePath);
+}
+
+export async function loadSidebars(
+  sidebarFilePath: string | false | undefined,
+  options: SidebarProcessorParams,
+): Promise<Sidebars> {
+  try {
+    const sidebarsConfig = await loadSidebarsFileUnsafe(sidebarFilePath);
+    const normalizedSidebars = normalizeSidebars(sidebarsConfig);
+    validateSidebars(normalizedSidebars);
+    const categoriesMetadata = await readCategoriesMetadata(
+      options.version.contentPath,
+    );
+    const processedSidebars = await processSidebars(
+      normalizedSidebars,
+      categoriesMetadata,
+      options,
+    );
+    return postProcessSidebars(processedSidebars, options);
+  } catch (err) {
+    logger.error`Sidebars file at path=${
+      sidebarFilePath as string
+    } failed to be loaded.`;
+    throw err;
+  }
+}

package/src/sidebars/normalization.ts

@@ -0,0 +1,85 @@
+/**
+ * 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 logger from '@docusaurus/logger';
+import {isCategoriesShorthand} from './utils';
+import type {
+  NormalizedSidebarItem,
+  NormalizedSidebar,
+  NormalizedSidebars,
+  SidebarCategoriesShorthand,
+  SidebarItemCategoryConfig,
+  SidebarItemConfig,
+  SidebarConfig,
+  SidebarsConfig,
+  NormalizedSidebarItemCategory,
+} from './types';
+
+function normalizeCategoriesShorthand(
+  sidebar: SidebarCategoriesShorthand,
+): SidebarItemCategoryConfig[] {
+  return Object.entries(sidebar).map(([label, items]) => ({
+    type: 'category',
+    label,
+    items,
+  }));
+}
+
+/**
+ * Normalizes recursively item and all its children. Ensures that at the end
+ * each item will be an object with the corresponding type.
+ */
+export function normalizeItem(
+  item: SidebarItemConfig,
+): NormalizedSidebarItem[] {
+  if (typeof item === 'string') {
+    return [{type: 'doc', id: item}];
+  }
+  if (isCategoriesShorthand(item)) {
+    // This will never throw anyways
+    return normalizeSidebar(item, 'sidebar items slice');
+  }
+  if (item.type === 'category') {
+    const normalizedCategory: NormalizedSidebarItemCategory = {
+      ...item,
+      items: normalizeSidebar(
+        item.items,
+        logger.interpolate`code=${'items'} of the category name=${item.label}`,
+      ),
+    };
+    return [normalizedCategory];
+  }
+  return [item];
+}
+
+function normalizeSidebar(
+  sidebar: SidebarConfig,
+  place: string,
+): NormalizedSidebar {
+  if (!Array.isArray(sidebar) && !isCategoriesShorthand(sidebar)) {
+    throw new Error(
+      logger.interpolate`Invalid sidebar items collection code=${JSON.stringify(
+        sidebar,
+      )} in ${place}: it must either be an array of sidebar items or a shorthand notation (which doesn't contain a code=${'type'} property). See url=${'https://docusaurus.io/docs/sidebar/items'} for all valid syntaxes.`,
+    );
+  }
+
+  const normalizedSidebar = Array.isArray(sidebar)
+    ? sidebar
+    : normalizeCategoriesShorthand(sidebar);
+
+  return normalizedSidebar.flatMap((subItem) => normalizeItem(subItem));
+}
+
+export function normalizeSidebars(
+  sidebars: SidebarsConfig,
+): NormalizedSidebars {
+  return _.mapValues(sidebars, (sidebar, id) =>
+    normalizeSidebar(sidebar, logger.interpolate`sidebar name=${id}`),
+  );
+}

package/src/sidebars/postProcessor.ts

@@ -0,0 +1,112 @@
+/**
+ * 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 {normalizeUrl} from '@docusaurus/utils';
+import {getDocIds} from '../docs';
+import type {
+  SidebarItem,
+  Sidebars,
+  SidebarProcessorParams,
+  ProcessedSidebarItemCategory,
+  ProcessedSidebarItem,
+  ProcessedSidebars,
+  SidebarItemCategoryLink,
+} from './types';
+
+export type SidebarPostProcessorParams = SidebarProcessorParams & {
+  draftIds: Set<string>;
+};
+
+function normalizeCategoryLink(
+  category: ProcessedSidebarItemCategory,
+  params: SidebarPostProcessorParams,
+): SidebarItemCategoryLink | undefined {
+  if (category.link?.type === 'doc' && params.draftIds.has(category.link.id)) {
+    return undefined;
+  }
+  if (category.link?.type === 'generated-index') {
+    // Default slug logic can be improved
+    const getDefaultSlug = () =>
+      `/category/${params.categoryLabelSlugger.slug(category.label)}`;
+    const slug = category.link.slug ?? getDefaultSlug();
+    const permalink = normalizeUrl([params.version.path, slug]);
+    return {
+      ...category.link,
+      slug,
+      permalink,
+    };
+  }
+  return category.link;
+}
+
+function postProcessSidebarItem(
+  item: ProcessedSidebarItem,
+  params: SidebarPostProcessorParams,
+): SidebarItem | null {
+  if (item.type === 'category') {
+    // Fail-fast if there's actually no subitems, no because all subitems are
+    // drafts. This is likely a configuration mistake.
+    if (item.items.length === 0 && !item.link) {
+      throw new Error(
+        `Sidebar category ${item.label} has neither any subitem nor a link. This makes this item not able to link to anything.`,
+      );
+    }
+    const category = {
+      ...item,
+      collapsed: item.collapsed ?? params.sidebarOptions.sidebarCollapsed,
+      collapsible: item.collapsible ?? params.sidebarOptions.sidebarCollapsible,
+      link: normalizeCategoryLink(item, params),
+      items: item.items
+        .map((subItem) => postProcessSidebarItem(subItem, params))
+        .filter((v): v is SidebarItem => Boolean(v)),
+    };
+    // If the current category doesn't have subitems, we render a normal link
+    // instead.
+    if (category.items.length === 0) {
+      // Doesn't make sense to render an empty generated index page, so we
+      // filter the entire category out as well.
+      if (
+        !category.link ||
+        category.link.type === 'generated-index' ||
+        params.draftIds.has(category.link.id)
+      ) {
+        return null;
+      }
+      return {
+        type: 'doc',
+        label: category.label,
+        id: category.link.id,
+      };
+    }
+    // A non-collapsible category can't be collapsed!
+    if (!category.collapsible) {
+      category.collapsed = false;
+    }
+    return category;
+  }
+  if (
+    (item.type === 'doc' || item.type === 'ref') &&
+    params.draftIds.has(item.id)
+  ) {
+    return null;
+  }
+  return item;
+}
+
+export function postProcessSidebars(
+  sidebars: ProcessedSidebars,
+  params: SidebarProcessorParams,
+): Sidebars {
+  const draftIds = new Set(params.drafts.flatMap(getDocIds));
+
+  return _.mapValues(sidebars, (sidebar) =>
+    sidebar
+      .map((item) => postProcessSidebarItem(item, {...params, draftIds}))
+      .filter((v): v is SidebarItem => Boolean(v)),
+  );
+}

package/src/sidebars/processor.ts

@@ -0,0 +1,123 @@
+/**
+ * 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 combinePromises from 'combine-promises';
+import {DefaultSidebarItemsGenerator} from './generator';
+import {validateSidebars} from './validation';
+import {isCategoryIndex} from '../docs';
+import type {
+  DocMetadataBase,
+  VersionMetadata,
+} from '@docusaurus/plugin-content-docs';
+import type {
+  NormalizedSidebarItem,
+  NormalizedSidebar,
+  NormalizedSidebars,
+  SidebarItemsGeneratorDoc,
+  SidebarItemsGeneratorVersion,
+  SidebarItemAutogenerated,
+  ProcessedSidebarItem,
+  ProcessedSidebar,
+  ProcessedSidebars,
+  SidebarProcessorParams,
+  CategoryMetadataFile,
+} from './types';
+
+function toSidebarItemsGeneratorDoc(
+  doc: DocMetadataBase,
+): SidebarItemsGeneratorDoc {
+  return _.pick(doc, [
+    'id',
+    'unversionedId',
+    'title',
+    '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,
+  categoriesMetadata: {[filePath: string]: CategoryMetadataFile},
+  params: SidebarProcessorParams,
+): Promise<ProcessedSidebar> {
+  const {sidebarItemsGenerator, numberPrefixParser, docs, version} = params;
+
+  // Just a minor lazy transformation optimization
+  const getSidebarItemsGeneratorDocsAndVersion = _.memoize(() => ({
+    docs: docs.map(toSidebarItemsGeneratorDoc),
+    version: toSidebarItemsGeneratorVersion(version),
+  }));
+
+  async function processAutoGeneratedItem(
+    item: SidebarItemAutogenerated,
+  ): Promise<ProcessedSidebarItem[]> {
+    const generatedItems = await sidebarItemsGenerator({
+      item,
+      numberPrefixParser,
+      defaultSidebarItemsGenerator: DefaultSidebarItemsGenerator,
+      isCategoryIndex,
+      ...getSidebarItemsGeneratorDocsAndVersion(),
+      categoriesMetadata,
+    });
+    // Process again... weird but sidebar item generated might generate some
+    // auto-generated items?
+    // TODO repeatedly process & unwrap autogenerated items until there are no
+    // more autogenerated items, or when loop count (e.g. 10) is reached
+    return processItems(generatedItems);
+  }
+
+  async function processItem(
+    item: NormalizedSidebarItem,
+  ): Promise<ProcessedSidebarItem[]> {
+    if (item.type === 'category') {
+      return [
+        {
+          ...item,
+          items: (await Promise.all(item.items.map(processItem))).flat(),
+        },
+      ];
+    }
+    if (item.type === 'autogenerated') {
+      return processAutoGeneratedItem(item);
+    }
+    return [item];
+  }
+
+  async function processItems(
+    items: NormalizedSidebarItem[],
+  ): Promise<ProcessedSidebarItem[]> {
+    return (await Promise.all(items.map(processItem))).flat();
+  }
+
+  const processedSidebar = await processItems(unprocessedSidebar);
+  return processedSidebar;
+}
+
+export async function processSidebars(
+  unprocessedSidebars: NormalizedSidebars,
+  categoriesMetadata: {[filePath: string]: CategoryMetadataFile},
+  params: SidebarProcessorParams,
+): Promise<ProcessedSidebars> {
+  const processedSidebars = await combinePromises(
+    _.mapValues(unprocessedSidebars, (unprocessedSidebar) =>
+      processSidebar(unprocessedSidebar, categoriesMetadata, params),
+    ),
+  );
+  validateSidebars(processedSidebars);
+  return processedSidebars;
+}

package/src/sidebars/types.ts

@@ -0,0 +1,275 @@
+/**
+ * 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 {Optional, Required} from 'utility-types';
+import type {
+  NumberPrefixParser,
+  SidebarOptions,
+  CategoryIndexMatcher,
+  DocMetadataBase,
+  VersionMetadata,
+} from '@docusaurus/plugin-content-docs';
+import type {Slugger} from '@docusaurus/utils';
+
+// Makes all properties visible when hovering over the type
+type Expand<T extends {[x: string]: unknown}> = {[P in keyof T]: T[P]};
+
+export type SidebarItemBase = {
+  className?: string;
+  customProps?: {[key: string]: unknown};
+};
+
+export type SidebarItemDoc = SidebarItemBase & {
+  type: 'doc' | 'ref';
+  label?: string;
+  id: string;
+};
+
+export type SidebarItemHtml = SidebarItemBase & {
+  type: 'html';
+  value: string;
+  defaultStyle?: boolean;
+};
+
+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;
+};
+
+export type SidebarItemCategoryLinkDoc = {type: 'doc'; id: string};
+
+export type SidebarItemCategoryLinkGeneratedIndexConfig = {
+  type: 'generated-index';
+  slug?: string;
+  title?: string;
+  description?: string;
+  image?: string;
+  keywords?: string | readonly string[];
+};
+export type SidebarItemCategoryLinkGeneratedIndex = {
+  type: 'generated-index';
+  slug: string;
+  permalink: string;
+  title?: string;
+  description?: string;
+  image?: string;
+  keywords?: string | readonly string[];
+};
+
+export type SidebarItemCategoryLinkConfig =
+  | SidebarItemCategoryLinkDoc
+  | SidebarItemCategoryLinkGeneratedIndexConfig;
+
+export type SidebarItemCategoryLink =
+  | SidebarItemCategoryLinkDoc
+  | SidebarItemCategoryLinkGeneratedIndex;
+
+// The user-given configuration in sidebars.js, before normalization
+export type SidebarItemCategoryConfig = Expand<
+  Optional<SidebarItemCategoryBase, 'collapsed' | 'collapsible'> & {
+    items: SidebarCategoriesShorthand | SidebarItemConfig[];
+    link?: SidebarItemCategoryLinkConfig;
+  }
+>;
+
+export type SidebarCategoriesShorthand = {
+  [sidebarCategory: string]: SidebarCategoriesShorthand | SidebarItemConfig[];
+};
+
+export type SidebarItemConfig =
+  | SidebarItemDoc
+  | SidebarItemHtml
+  | 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<
+  Optional<SidebarItemCategoryBase, 'collapsed' | 'collapsible'> & {
+    items: NormalizedSidebarItem[];
+    link?: SidebarItemCategoryLinkConfig;
+  }
+>;
+
+export type NormalizedSidebarItem =
+  | SidebarItemDoc
+  | SidebarItemHtml
+  | SidebarItemLink
+  | NormalizedSidebarItemCategory
+  | SidebarItemAutogenerated;
+
+export type NormalizedSidebar = NormalizedSidebarItem[];
+export type NormalizedSidebars = {
+  [sidebarId: string]: NormalizedSidebar;
+};
+
+export type ProcessedSidebarItemCategory = Expand<
+  Optional<SidebarItemCategoryBase, 'collapsed' | 'collapsible'> & {
+    items: ProcessedSidebarItem[];
+    link?: SidebarItemCategoryLinkConfig;
+  }
+>;
+export type ProcessedSidebarItem =
+  | SidebarItemDoc
+  | SidebarItemHtml
+  | SidebarItemLink
+  | ProcessedSidebarItemCategory;
+export type ProcessedSidebar = ProcessedSidebarItem[];
+export type ProcessedSidebars = {
+  [sidebarId: string]: ProcessedSidebar;
+};
+
+export type SidebarItemCategory = Expand<
+  SidebarItemCategoryBase & {
+    items: SidebarItem[];
+    link?: SidebarItemCategoryLink;
+  }
+>;
+
+export type SidebarItemCategoryWithLink = Required<SidebarItemCategory, 'link'>;
+
+export type SidebarItemCategoryWithGeneratedIndex =
+  SidebarItemCategoryWithLink & {link: SidebarItemCategoryLinkGeneratedIndex};
+
+export type SidebarItem =
+  | SidebarItemDoc
+  | SidebarItemHtml
+  | SidebarItemLink
+  | SidebarItemCategory;
+
+// A sidebar item that is part of the previous/next ordered navigation
+export type SidebarNavigationItem =
+  | SidebarItemDoc
+  | SidebarItemCategoryWithLink;
+
+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[];
+    href?: string;
+  }
+>;
+
+export type PropSidebarItemLink = SidebarItemLink & {
+  docId?: string;
+};
+
+export type PropSidebarItemHtml = SidebarItemHtml;
+
+export type PropSidebarItem =
+  | PropSidebarItemLink
+  | PropSidebarItemCategory
+  | PropSidebarItemHtml;
+export type PropSidebar = PropSidebarItem[];
+export type PropSidebars = {
+  [sidebarId: string]: PropSidebar;
+};
+
+export type PropSidebarBreadcrumbsItem =
+  | PropSidebarItemLink
+  | PropSidebarItemCategory;
+
+export type CategoryMetadataFile = {
+  label?: string;
+  position?: number;
+  collapsed?: boolean;
+  collapsible?: boolean;
+  className?: string;
+  link?: SidebarItemCategoryLinkConfig | null;
+  customProps?: {[key: string]: unknown};
+
+  // TODO should we allow "items" here? how would this work? would an
+  // "autogenerated" type be allowed?
+  // This mkdocs plugin do something like that: https://github.com/lukasgeiter/mkdocs-awesome-pages-plugin/
+  // cf comment: https://github.com/facebook/docusaurus/issues/3464#issuecomment-784765199
+};
+
+// Reduce API surface for options.sidebarItemsGenerator
+// The user-provided generator fn should receive only a subset of metadata
+// A change to any of these metadata can be considered as a breaking change
+export type SidebarItemsGeneratorDoc = Pick<
+  DocMetadataBase,
+  | 'id'
+  | 'unversionedId'
+  | 'title'
+  | 'frontMatter'
+  | 'source'
+  | 'sourceDirName'
+  | 'sidebarPosition'
+>;
+export type SidebarItemsGeneratorVersion = Pick<
+  VersionMetadata,
+  'versionName' | 'contentPath'
+>;
+
+export type SidebarItemsGeneratorArgs = {
+  /** The sidebar item with type "autogenerated" to be transformed. */
+  item: SidebarItemAutogenerated;
+  /** Useful metadata for the version this sidebar belongs to. */
+  version: SidebarItemsGeneratorVersion;
+  /** All the docs of that version (unfiltered). */
+  docs: SidebarItemsGeneratorDoc[];
+  /** Number prefix parser configured for this plugin. */
+  numberPrefixParser: NumberPrefixParser;
+  /** The default category index matcher which you can override. */
+  isCategoryIndex: CategoryIndexMatcher;
+  /**
+   * Key is the path relative to the doc content directory, value is the
+   * category metadata file's content.
+   */
+  categoriesMetadata: {[filePath: string]: CategoryMetadataFile};
+};
+export type SidebarItemsGenerator = (
+  generatorArgs: SidebarItemsGeneratorArgs,
+) => NormalizedSidebar | Promise<NormalizedSidebar>;
+
+export type SidebarItemsGeneratorOption = (
+  generatorArgs: {
+    /**
+     * Useful to re-use/enhance the default sidebar generation logic from
+     * Docusaurus.
+     * @see https://github.com/facebook/docusaurus/issues/4640#issuecomment-822292320
+     */
+    defaultSidebarItemsGenerator: SidebarItemsGenerator;
+  } & SidebarItemsGeneratorArgs,
+) => NormalizedSidebar | Promise<NormalizedSidebar>;
+
+export type SidebarProcessorParams = {
+  sidebarItemsGenerator: SidebarItemsGeneratorOption;
+  numberPrefixParser: NumberPrefixParser;
+  docs: DocMetadataBase[];
+  drafts: DocMetadataBase[];
+  version: VersionMetadata;
+  categoryLabelSlugger: Slugger;
+  sidebarOptions: SidebarOptions;
+};