@docusaurus/plugin-content-docs 2.0.0-beta.12faed89d → 2.0.0-beta.13

package/src/sidebars/__tests__/validation.test.ts

@@ -0,0 +1,105 @@
+/**
+ * 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 {validateSidebars, validateCategoryMetadataFile} from '../validation';
+import {CategoryMetadataFile} from '../generator';
+import {SidebarsConfig} from '../types';
+
+describe('validateSidebars', () => {
+  // TODO add more tests
+
+  // TODO it seems many error cases are not validated properly
+  // and error messages are quite bad
+  test('throw for bad value', async () => {
+    expect(() => validateSidebars({sidebar: [{type: 42}]}))
+      .toThrowErrorMatchingInlineSnapshot(`
+      "{
+        \\"type\\": 42,
+        \\"undefined\\" [1]: -- missing --
+      }
+      
+      [1] Unknown sidebar item type \\"42\\"."
+    `);
+  });
+
+  test('accept empty object', async () => {
+    const sidebars: SidebarsConfig = {};
+    validateSidebars(sidebars);
+  });
+
+  test('accept valid values', async () => {
+    const sidebars: SidebarsConfig = {
+      sidebar1: [
+        {type: 'doc', id: 'doc1'},
+        {type: 'doc', id: 'doc2'},
+        {
+          type: 'category',
+          label: 'Category',
+          items: [{type: 'doc', id: 'doc3'}],
+        },
+      ],
+    };
+    validateSidebars(sidebars);
+  });
+});
+
+describe('validateCategoryMetadataFile', () => {
+  // TODO add more tests
+
+  test('throw for bad value', async () => {
+    expect(() =>
+      validateCategoryMetadataFile(42),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `"\\"value\\" must be of type object"`,
+    );
+  });
+
+  test('accept empty object', async () => {
+    const content: CategoryMetadataFile = {};
+    expect(validateCategoryMetadataFile(content)).toEqual(content);
+  });
+
+  test('accept valid values', async () => {
+    const content: CategoryMetadataFile = {
+      className: 'className',
+      label: 'Category Label',
+      link: {
+        type: 'generated-index',
+        slug: 'slug',
+        title: 'title',
+        description: 'description',
+      },
+      collapsible: true,
+      collapsed: true,
+      position: 3,
+    };
+    expect(validateCategoryMetadataFile(content)).toEqual(content);
+  });
+
+  test('rejects permalink', async () => {
+    const content: CategoryMetadataFile = {
+      className: 'className',
+      label: 'Category Label',
+      link: {
+        type: 'generated-index',
+        slug: 'slug',
+        // @ts-expect-error: rejected on purpose
+        permalink: 'somePermalink',
+        title: 'title',
+        description: 'description',
+      },
+      collapsible: true,
+      collapsed: true,
+      position: 3,
+    };
+    expect(() =>
+      validateCategoryMetadataFile(content),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `"\\"link.permalink\\" is not allowed"`,
+    );
+  });
+});

package/src/sidebars/generator.ts

@@ -0,0 +1,310 @@
+/**
+ * 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 {
+  SidebarItem,
+  SidebarItemDoc,
+  SidebarItemCategory,
+  SidebarItemsGenerator,
+  SidebarItemsGeneratorDoc,
+  SidebarItemCategoryLink,
+  SidebarItemCategoryLinkConfig,
+} from './types';
+import {sortBy, last} from 'lodash';
+import {addTrailingSlash, posixPath} from '@docusaurus/utils';
+import chalk from 'chalk';
+import path from 'path';
+import fs from 'fs-extra';
+import Yaml from 'js-yaml';
+import {validateCategoryMetadataFile} from './validation';
+import {createDocsByIdIndex, isConventionalDocIndex} from '../docs';
+
+const BreadcrumbSeparator = '/';
+// To avoid possible name clashes with a folder of the same name as the ID
+const docIdPrefix = '$doc$/';
+
+// 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}';
+
+export type CategoryMetadataFile = {
+  label?: string;
+  position?: number;
+  collapsed?: boolean;
+  collapsible?: boolean;
+  className?: string;
+  link?: SidebarItemCategoryLinkConfig;
+
+  // 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
+};
+
+type WithPosition<T> = T & {position?: number};
+
+/**
+ * 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 id prefixed with '$doc$/', and value is null
+ */
+type Dir = {
+  [item: string]: Dir | null;
+};
+
+// TODO I now believe we should read all the category metadata files ahead of time: we may need this metadata to customize docs metadata
+// Example use-case being able to disable number prefix parsing at the folder level, or customize the default route path segment for an intermediate directory...
+// TODO later if there is `CategoryFolder/with-category-name-doc.md`, we may want to read the metadata as yaml on it
+// see https://github.com/facebook/docusaurus/issues/3464#issuecomment-818670449
+async function readCategoryMetadataFile(
+  categoryDirPath: string,
+): Promise<CategoryMetadataFile | null> {
+  async function tryReadFile(filePath: string): Promise<CategoryMetadataFile> {
+    const contentString = await fs.readFile(filePath, {encoding: 'utf8'});
+    const unsafeContent = Yaml.load(contentString);
+    try {
+      return validateCategoryMetadataFile(unsafeContent);
+    } catch (e) {
+      console.error(
+        chalk.red(
+          `The docs sidebar category metadata file looks invalid!\nPath: ${filePath}`,
+        ),
+      );
+      throw e;
+    }
+  }
+  // eslint-disable-next-line no-restricted-syntax
+  for (const ext of ['.json', '.yml', '.yaml']) {
+    // Simpler to use only posix paths for mocking file metadata in tests
+    const filePath = posixPath(
+      path.join(categoryDirPath, `${CategoryMetadataFilenameBase}${ext}`),
+    );
+    if (await fs.pathExists(filePath)) {
+      return tryReadFile(filePath);
+    }
+  }
+  return null;
+}
+
+// Comment for this feature: https://github.com/facebook/docusaurus/issues/3464#issuecomment-818670449
+export const DefaultSidebarItemsGenerator: SidebarItemsGenerator = async ({
+  numberPrefixParser,
+  docs: allDocs,
+  options,
+  item: {dirName: autogenDir},
+  version,
+}) => {
+  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}.\nAvailable doc ids:\n- ${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) {
+      console.warn(
+        chalk.yellow(
+          `No docs found in dir ${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);
+      let currentDir = treeRoot; // We walk down the file's path to generate the fs structure
+      // eslint-disable-next-line no-restricted-syntax
+      for (const dir of breadcrumb) {
+        if (typeof currentDir[dir] === 'undefined') {
+          currentDir[dir] = {}; // Create new folder.
+        }
+        currentDir = currentDir[dir]!; // Go into the subdirectory.
+      }
+      currentDir[`${docIdPrefix}${doc.id}`] = null; // We've walked through the file path. Register the file in this directory.
+    });
+    return treeRoot;
+  }
+
+  /**
+   * Step 3. Recursively transform the tree-like file structure to sidebar items.
+   * (From a record to an array of items, akin to normalizing shorthand)
+   */
+  function generateSidebar(fsModel: Dir): Promise<WithPosition<SidebarItem>[]> {
+    function createDocItem(id: string): WithPosition<SidebarItemDoc> {
+      const {
+        sidebarPosition: position,
+        frontMatter: {sidebar_label: label, sidebar_class_name: className},
+      } = getDoc(id);
+      return {
+        type: 'doc',
+        id,
+        position,
+        // We don't want these fields to magically appear in the generated sidebar
+        ...(label !== undefined && {label}),
+        ...(className !== undefined && {className}),
+      };
+    }
+    async function createCategoryItem(
+      dir: Dir,
+      fullPath: string,
+      folderName: string,
+    ): Promise<WithPosition<SidebarItemCategory>> {
+      const categoryPath = path.join(version.contentPath, autogenDir, fullPath);
+      const categoryMetadata = await readCategoryMetadataFile(categoryPath);
+      const className = categoryMetadata?.className;
+      const {filename, numberPrefix} = numberPrefixParser(folderName);
+      const allItems = await Promise.all(
+        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.type === 'doc' && getLocalDocId(item.id) === localId,
+        ) as SidebarItemDoc | undefined;
+      }
+
+      function findConventionalCategoryDocLink(): SidebarItemDoc | undefined {
+        return allItems.find(
+          (item) =>
+            item.type === 'doc' && isConventionalDocIndex(getDoc(item.id)),
+        ) as SidebarItemDoc | undefined;
+      }
+
+      function getCategoryLinkedDocId(): string | undefined {
+        const link = categoryMetadata?.link;
+        if (link) {
+          if (link.type === 'doc') {
+            return findDocByLocalId(link.id)?.id || getDoc(link.id).id;
+          } else {
+            // We don't continue for other link types on purpose!
+            // IE if user decide to use type "generated-index", we should not pick a README.md file as the linked doc
+            return undefined;
+          }
+        }
+        // Apply default convention to pick index.md, README.md or <categoryName>.md as the category doc
+        return findConventionalCategoryDocLink()?.id;
+      }
+
+      const categoryLinkedDocId = getCategoryLinkedDocId();
+
+      const link: SidebarItemCategoryLink | undefined = categoryLinkedDocId
+        ? {
+            type: 'doc',
+            id: categoryLinkedDocId, // We "remap" a potentially "local id" to a "qualified id"
+          }
+        : // TODO typing issue
+          (categoryMetadata?.link as SidebarItemCategoryLink | undefined);
+
+      // If a doc is linked, remove it from the category subItems
+      const items = allItems.filter(
+        (item) => !(item.type === 'doc' && item.id === categoryLinkedDocId),
+      );
+
+      return {
+        type: 'category',
+        label: categoryMetadata?.label ?? filename,
+        collapsible:
+          categoryMetadata?.collapsible ?? options.sidebarCollapsible,
+        collapsed: categoryMetadata?.collapsed ?? options.sidebarCollapsed,
+        position: categoryMetadata?.position ?? numberPrefix,
+        ...(className !== undefined && {className}),
+        items,
+        ...(link && {link}),
+      };
+    }
+    async function dirToItem(
+      dir: Dir | null, // The directory item to be transformed.
+      itemKey: string, // For docs, it's the doc ID; for categories, it's used to generate the next `relativePath`.
+      fullPath: string, // `dir`'s full path relative to the autogen dir.
+    ): Promise<WithPosition<SidebarItem>> {
+      return dir
+        ? createCategoryItem(dir, fullPath, itemKey)
+        : createDocItem(itemKey.substring(docIdPrefix.length));
+    }
+    return Promise.all(
+      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 (ie a whole Category
+   * composed of multiple autogenerated items)
+   */
+  function sortItems(sidebarItems: WithPosition<SidebarItem>[]): SidebarItem[] {
+    const processedSidebarItems = sidebarItems.map((item) => {
+      if (item.type === 'category') {
+        return {...item, items: sortItems(item.items)};
+      }
+      return item;
+    });
+    const sortedSidebarItems = sortBy(
+      processedSidebarItems,
+      (item) => item.position,
+    );
+    return sortedSidebarItems.map(({position, ...item}) => item);
+  }
+  // TODO: the whole code is designed for pipeline operator
+  // return getAutogenDocs() |> treeify |> await generateSidebar(^) |> sortItems;
+  const docs = getAutogenDocs();
+  const fsModel = treeify(docs);
+  const sidebarWithPosition = await generateSidebar(fsModel);
+  const sortedSidebar = sortItems(sidebarWithPosition);
+  return sortedSidebar;
+};

package/src/sidebars/index.ts

@@ -0,0 +1,94 @@
+/**
+ * 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 {NormalizeSidebarsParams, PluginOptions} from '../types';
+import {validateSidebars} from './validation';
+import {normalizeSidebars} from './normalization';
+import {processSidebars, SidebarProcessorParams} from './processor';
+import path from 'path';
+import {createSlugger} from '@docusaurus/utils';
+
+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 loadSidebarsFileUnsafe(
+  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 loadSidebarsFile(
+  sidebarFilePath: string | false | undefined,
+): SidebarsConfig {
+  const sidebarsConfig = loadSidebarsFileUnsafe(sidebarFilePath);
+  validateSidebars(sidebarsConfig);
+  return sidebarsConfig;
+}
+
+export function loadNormalizedSidebars(
+  sidebarFilePath: string | false | undefined,
+  params: NormalizeSidebarsParams,
+): NormalizedSidebars {
+  return normalizeSidebars(loadSidebarsFile(sidebarFilePath), params);
+}
+
+// Note: sidebarFilePath must be absolute, use resolveSidebarPathOption
+export async function loadSidebars(
+  sidebarFilePath: string | false | undefined,
+  options: SidebarProcessorParams,
+): Promise<Sidebars> {
+  const normalizeSidebarsParams: NormalizeSidebarsParams = {
+    ...options.sidebarOptions,
+    version: options.version,
+    categoryLabelSlugger: createSlugger(),
+  };
+  const normalizedSidebars = loadNormalizedSidebars(
+    sidebarFilePath,
+    normalizeSidebarsParams,
+  );
+  return processSidebars(normalizedSidebars, options);
+}

package/src/sidebars/normalization.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 type {NormalizeSidebarsParams, SidebarOptions} from '../types';
+import type {
+  NormalizedSidebarItem,
+  NormalizedSidebar,
+  NormalizedSidebars,
+  SidebarCategoriesShorthand,
+  SidebarItemCategoryConfig,
+  SidebarItemConfig,
+  SidebarConfig,
+  SidebarsConfig,
+  SidebarItemCategoryLink,
+  NormalizedSidebarItemCategory,
+} from './types';
+import {isCategoriesShorthand} from './utils';
+import {mapValues} from 'lodash';
+import {normalizeUrl} from '@docusaurus/utils';
+
+function normalizeCategoryLink(
+  category: SidebarItemCategoryConfig,
+  params: NormalizeSidebarsParams,
+): SidebarItemCategoryLink | 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.versionPath, slug]);
+    return {
+      ...category.link,
+      slug,
+      permalink,
+    };
+  }
+  return category.link;
+}
+
+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.
+ */
+export function normalizeItem(
+  item: SidebarItemConfig,
+  options: NormalizeSidebarsParams,
+): NormalizedSidebarItem[] {
+  if (typeof item === 'string') {
+    return [
+      {
+        type: 'doc',
+        id: item,
+      },
+    ];
+  }
+  if (isCategoriesShorthand(item)) {
+    return normalizeCategoriesShorthand(item, options).flatMap((subItem) =>
+      normalizeItem(subItem, options),
+    );
+  }
+  if (item.type === 'category') {
+    const link = normalizeCategoryLink(item, options);
+    const normalizedCategory: NormalizedSidebarItemCategory = {
+      ...item,
+      link,
+      items: (item.items ?? []).flatMap((subItem) =>
+        normalizeItem(subItem, options),
+      ),
+      collapsible: item.collapsible ?? options.sidebarCollapsible,
+      collapsed: item.collapsed ?? options.sidebarCollapsed,
+    };
+    return [normalizedCategory];
+  }
+  return [item];
+}
+
+function normalizeSidebar(
+  sidebar: SidebarConfig,
+  options: NormalizeSidebarsParams,
+): NormalizedSidebar {
+  const normalizedSidebar = Array.isArray(sidebar)
+    ? sidebar
+    : normalizeCategoriesShorthand(sidebar, options);
+
+  return normalizedSidebar.flatMap((subItem) =>
+    normalizeItem(subItem, options),
+  );
+}
+
+export function normalizeSidebars(
+  sidebars: SidebarsConfig,
+  params: NormalizeSidebarsParams,
+): NormalizedSidebars {
+  return mapValues(sidebars, (items) => normalizeSidebar(items, params));
+}