@azerion/bunosaurus-plugin-content-docs 0.0.0-stage → 4.0.0

package/src/sidebars/generator.ts

@@ -0,0 +1,307 @@
+/**
+ * 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 path from 'node:path';
+import _ from 'lodash';
+import logger from '@docusaurus/logger';
+import {addTrailingSlash} from '@docusaurus/utils-common';
+import {createDocsByIdIndex, toCategoryIndexMatcherParam} from '../docs';
+import type {
+  SidebarItemDoc,
+  SidebarItemsGenerator,
+  SidebarItemsGeneratorDoc,
+  NormalizedSidebarItemCategory,
+  NormalizedSidebarItem,
+  SidebarItemCategoryLinkConfig,
+} from './types';
+
+const BreadcrumbSeparator = '/';
+
+// Just an alias to the make code more explicit
+function getLocalDocId(docId: string): string {
+  return _.last(docId.split('/'))!;
+}
+
+export const CategoryMetadataFilenameBase = '_category_';
+export const CategoryMetadataFilenamePattern = '_category_.{json,yml,yaml}';
+
+type WithPosition<T> = T & {
+  position?: number;
+  /** The source is the file/folder name */
+  source?: string;
+};
+
+/**
+ * A representation of the fs structure. For each object entry:
+ * If it's a folder, the key is the directory name, and value is the directory
+ * content; If it's a doc file, the key is the doc's source file name, and value
+ * is the doc ID
+ */
+type Dir = {
+  [item: string]: Dir | string;
+};
+
+// Comment for this feature: https://github.com/facebook/docusaurus/issues/3464#issuecomment-818670449
+export const DefaultSidebarItemsGenerator: SidebarItemsGenerator = ({
+  numberPrefixParser,
+  isCategoryIndex,
+  docs: allDocs,
+  item: {dirName: autogenDir},
+  categoriesMetadata,
+}) => {
+  const docsById = createDocsByIdIndex(allDocs);
+  const findDoc = (docId: string): SidebarItemsGeneratorDoc | undefined =>
+    docsById[docId];
+  const getDoc = (docId: string): SidebarItemsGeneratorDoc => {
+    const doc = findDoc(docId);
+    if (!doc) {
+      throw new Error(
+        `Can't find any doc with ID ${docId}.
+Available doc IDs:
+- ${Object.keys(docsById).join('\n- ')}`,
+      );
+    }
+    return doc;
+  };
+
+  /**
+   * Step 1. Extract the docs that are in the autogen dir.
+   */
+  function getAutogenDocs(): SidebarItemsGeneratorDoc[] {
+    function isInAutogeneratedDir(doc: SidebarItemsGeneratorDoc) {
+      return (
+        // Doc at the root of the autogenerated sidebar dir
+        doc.sourceDirName === autogenDir ||
+        // Autogen dir is . and doc is in subfolder
+        autogenDir === '.' ||
+        // Autogen dir is not . and doc is in subfolder
+        // "api/myDoc" startsWith "api/" (note "api2/myDoc" is not included)
+        doc.sourceDirName.startsWith(addTrailingSlash(autogenDir))
+      );
+    }
+    const docs = allDocs.filter(isInAutogeneratedDir);
+
+    if (docs.length === 0) {
+      logger.warn`No docs found in path=${autogenDir}: can't auto-generate a sidebar.`;
+    }
+    return docs;
+  }
+
+  /**
+   * Step 2. Turn the linear file list into a tree structure.
+   */
+  function treeify(docs: SidebarItemsGeneratorDoc[]): Dir {
+    // Get the category breadcrumb of a doc (relative to the dir of the
+    // autogenerated sidebar item)
+    // autogenDir=a/b and docDir=a/b/c/d => returns [c, d]
+    // autogenDir=a/b and docDir=a/b => returns []
+    // TODO: try to use path.relative()
+    function getRelativeBreadcrumb(doc: SidebarItemsGeneratorDoc): string[] {
+      return autogenDir === doc.sourceDirName
+        ? []
+        : doc.sourceDirName
+            .replace(addTrailingSlash(autogenDir), '')
+            .split(BreadcrumbSeparator);
+    }
+    const treeRoot: Dir = {};
+    docs.forEach((doc) => {
+      const breadcrumb = getRelativeBreadcrumb(doc);
+      // We walk down the file's path to generate the fs structure
+      let currentDir = treeRoot;
+      breadcrumb.forEach((dir) => {
+        if (typeof currentDir[dir] === 'undefined') {
+          currentDir[dir] = {}; // Create new folder.
+        }
+        currentDir = currentDir[dir] as Dir; // Go into the subdirectory.
+      });
+      // We've walked through the path. Register the file in this directory.
+      currentDir[path.basename(doc.source)] = doc.id;
+    });
+    return treeRoot;
+  }
+
+  /**
+   * Step 3. Recursively transform the tree-like structure to sidebar items.
+   * (From a record to an array of items, akin to normalizing shorthand)
+   */
+  function generateSidebar(
+    fsModel: Dir,
+  ): WithPosition<NormalizedSidebarItem>[] {
+    function createDocItem(
+      id: string,
+      fullPath: string,
+      fileName: string,
+    ): WithPosition<SidebarItemDoc> {
+      const {
+        sidebarPosition: position,
+        frontMatter: {
+          sidebar_key: key,
+          sidebar_label: label,
+          sidebar_class_name: className,
+          sidebar_custom_props: customProps,
+        },
+      } = getDoc(id);
+      return {
+        type: 'doc',
+        id,
+        position,
+        source: fileName,
+        // We don't want these fields to magically appear in the generated
+        // sidebar
+        ...(key !== undefined && {key}),
+        ...(label !== undefined && {label}),
+        ...(className !== undefined && {className}),
+        ...(customProps !== undefined && {customProps}),
+      };
+    }
+    function createCategoryItem(
+      dir: Dir,
+      fullPath: string,
+      folderName: string,
+    ): WithPosition<NormalizedSidebarItemCategory> {
+      const categoryMetadata =
+        categoriesMetadata[path.posix.join(autogenDir, fullPath)];
+      const allItems = Object.entries(dir).map(([key, content]) =>
+        dirToItem(content, key, `${fullPath}/${key}`),
+      );
+
+      // Try to match a doc inside the category folder,
+      // using the "local id" (myDoc) or "qualified id" (dirName/myDoc)
+      function findDocByLocalId(localId: string): SidebarItemDoc | undefined {
+        return allItems.find(
+          (item): item is SidebarItemDoc =>
+            item.type === 'doc' && getLocalDocId(item.id) === localId,
+        );
+      }
+
+      function findConventionalCategoryDocLink(): SidebarItemDoc | undefined {
+        return allItems.find((item): item is SidebarItemDoc => {
+          if (item.type !== 'doc') {
+            return false;
+          }
+          const doc = getDoc(item.id);
+          return isCategoryIndex(toCategoryIndexMatcherParam(doc));
+        });
+      }
+
+      // In addition to the ID, this function also retrieves metadata of the
+      // linked doc that could be used as fallback values for category metadata
+      function getCategoryLinkedDocMetadata():
+        | {
+            id: string;
+            key?: string;
+            position?: number;
+            label?: string;
+            customProps?: {[key: string]: unknown};
+            className?: string;
+          }
+        | undefined {
+        const link = categoryMetadata?.link;
+        if (link !== undefined && link?.type !== 'doc') {
+          // If a link is explicitly specified, we won't apply conventions
+          return undefined;
+        }
+        const id = link
+          ? (findDocByLocalId(link.id)?.id ?? getDoc(link.id).id)
+          : findConventionalCategoryDocLink()?.id;
+        if (!id) {
+          return undefined;
+        }
+        const doc = getDoc(id);
+        return {
+          id,
+          position: doc.sidebarPosition,
+          key: doc.frontMatter.sidebar_key,
+          label: doc.frontMatter.sidebar_label ?? doc.title,
+          customProps: doc.frontMatter.sidebar_custom_props,
+          className: doc.frontMatter.sidebar_class_name,
+        };
+      }
+      const categoryLinkedDoc = getCategoryLinkedDocMetadata();
+      const link: SidebarItemCategoryLinkConfig | null | undefined =
+        categoryLinkedDoc
+          ? {
+              type: 'doc',
+              id: categoryLinkedDoc.id, // We "remap" a potentially "local id" to a "qualified id"
+            }
+          : categoryMetadata?.link;
+      // If a doc is linked, remove it from the category subItems
+      const items = allItems.filter(
+        (item) => !(item.type === 'doc' && item.id === categoryLinkedDoc?.id),
+      );
+
+      const className =
+        categoryMetadata?.className ?? categoryLinkedDoc?.className;
+      const customProps =
+        categoryMetadata?.customProps ?? categoryLinkedDoc?.customProps;
+      const {filename, numberPrefix} = numberPrefixParser(folderName);
+
+      const key = categoryMetadata?.key ?? categoryLinkedDoc?.key;
+
+      return {
+        type: 'category',
+        label: categoryMetadata?.label ?? categoryLinkedDoc?.label ?? filename,
+        collapsible: categoryMetadata?.collapsible,
+        collapsed: categoryMetadata?.collapsed,
+        position:
+          categoryMetadata?.position ??
+          categoryLinkedDoc?.position ??
+          numberPrefix,
+        source: folderName,
+        ...(customProps !== undefined && {customProps}),
+        ...(className !== undefined && {className}),
+        items,
+        ...(categoryMetadata?.description && {
+          description: categoryMetadata?.description,
+        }),
+        ...(key && {key}),
+        ...(link && {link}),
+      };
+    }
+    function dirToItem(
+      dir: Dir | string, // The directory item to be transformed.
+      itemKey: string, // File/folder name; for categories, it's used to generate the next `relativePath`.
+      fullPath: string, // `dir`'s full path relative to the autogen dir.
+    ): WithPosition<NormalizedSidebarItem> {
+      return typeof dir === 'object'
+        ? createCategoryItem(dir, fullPath, itemKey)
+        : createDocItem(dir, fullPath, itemKey);
+    }
+    return Object.entries(fsModel).map(([key, content]) =>
+      dirToItem(content, key, key),
+    );
+  }
+
+  /**
+   * Step 4. Recursively sort the categories/docs + remove the "position"
+   * attribute from final output. Note: the "position" is only used to sort
+   * "inside" a sidebar slice. It is not used to sort across multiple
+   * consecutive sidebar slices (i.e. a whole category composed of multiple
+   * autogenerated items)
+   */
+  function sortItems(
+    sidebarItems: WithPosition<NormalizedSidebarItem>[],
+  ): NormalizedSidebarItem[] {
+    const processedSidebarItems = sidebarItems.map((item) => {
+      if (item.type === 'category') {
+        return {...item, items: sortItems(item.items)};
+      }
+      return item;
+    });
+    const sortedSidebarItems = _.sortBy(processedSidebarItems, [
+      'position',
+      'source',
+    ]);
+    return sortedSidebarItems.map(({position, source, ...item}) => item);
+  }
+  // TODO: the whole code is designed for pipeline operator
+  const docs = getAutogenDocs();
+  const fsModel = treeify(docs);
+  const sidebarWithPosition = generateSidebar(fsModel);
+  const sortedSidebar = sortItems(sidebarWithPosition);
+  return sortedSidebar;
+};

package/src/sidebars/index.ts

@@ -0,0 +1,130 @@
+/**
+ * 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 path from 'node:path';
+import _ from 'lodash';
+import logger from '@docusaurus/logger';
+import {loadFreshModule} from '@docusaurus/utils';
+import {glob} from '@docusaurus/glob';
+import * as Yaml from 'js-yaml';
+import combinePromises from 'combine-promises';
+import {fs, pathExists} from '@docusaurus/fs';
+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 glob('**/_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;
+      }
+    }),
+  );
+}
+
+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 pathExists(sidebarFilePath))) {
+    return DisabledSidebars;
+  }
+
+  // We don't want sidebars to be cached because of hot reloading.
+  const module = await loadFreshModule(sidebarFilePath, {default: true});
+
+  // TODO unsafe, need to refactor and improve validation
+  return module as SidebarsConfig;
+}
+
+export async function loadSidebarsFile(
+  sidebarFilePath: string | false | undefined,
+): Promise<SidebarsConfig> {
+  const sidebars = await loadSidebarsFileUnsafe(sidebarFilePath);
+
+  // TODO unsafe, need to refactor and improve validation
+  return sidebars as SidebarsConfig;
+}
+
+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,91 @@
+/**
+ * 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 === 'doc' || item.type === 'ref') &&
+    typeof item.label === 'string'
+  ) {
+    return [{...item, translatable: true}];
+  }
+  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,115 @@
+/**
+ * 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 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;
+      }
+      const {label, className, customProps} = category;
+      return {
+        type: 'doc',
+        id: category.link.id,
+        label,
+        ...(className && {className}),
+        ...(customProps && {customProps}),
+      };
+    }
+    // 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.map((d) => d.id));
+
+  return _.mapValues(sidebars, (sidebar) =>
+    sidebar
+      .map((item) => postProcessSidebarItem(item, {...params, draftIds}))
+      .filter((v): v is SidebarItem => Boolean(v)),
+  );
+}