@docusaurus/plugin-content-docs 0.0.0-4071 → 0.0.0-4075

package/src/sidebars/validation.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 {Joi, URISchema} from '@docusaurus/utils-validation';
+import {
+  SidebarItemConfig,
+  SidebarCategoriesShorthand,
+  SidebarItemBase,
+  SidebarItemAutogenerated,
+  SidebarItemDoc,
+  SidebarItemLink,
+  SidebarItemCategoryConfig,
+  SidebarsConfig,
+  isCategoriesShorthand,
+} from './types';
+
+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 sidebarItemLinkSchema = sidebarItemBaseSchema.append<SidebarItemLink>({
+  type: 'link',
+  href: URISchema.required(),
+  label: Joi.string()
+    .required()
+    .messages({'any.unknown': '"label" must be a string'}),
+});
+
+const sidebarItemCategorySchema =
+  sidebarItemBaseSchema.append<SidebarItemCategoryConfig>({
+    type: 'category',
+    label: Joi.string()
+      .required()
+      .messages({'any.unknown': '"label" must be a string'}),
+    // TODO: Joi doesn't allow mutual recursion. See https://github.com/sideway/joi/issues/2611
+    items: Joi.array()
+      .required()
+      .messages({'any.unknown': '"items" must be an array'}), // .items(Joi.link('#sidebarItemSchema')),
+    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.Schema<SidebarItemConfig> = Joi.object()
+  .when('.type', {
+    switch: [
+      {is: 'link', then: sidebarItemLinkSchema},
+      {
+        is: Joi.string().valid('doc', 'ref').required(),
+        then: sidebarItemDocSchema,
+      },
+      {is: 'autogenerated', then: sidebarItemAutogeneratedSchema},
+      {is: 'category', then: sidebarItemCategorySchema},
+      {
+        is: 'subcategory',
+        then: Joi.forbidden().messages({
+          'any.unknown':
+            'Docusaurus v2: "subcategory" has been renamed as "category".',
+        }),
+      },
+      {
+        is: Joi.string().required(),
+        then: Joi.forbidden().messages({
+          'any.unknown': 'Unknown sidebar item type "{.type}".',
+        }),
+      },
+    ],
+  })
+  .id('sidebarItemSchema');
+
+function validateSidebarItem(item: unknown): asserts item is SidebarItemConfig {
+  if (typeof item === 'string') {
+    return;
+  }
+  // TODO: remove once with proper Joi support
+  // Because we can't use Joi to validate nested items (see above), we do it manually
+  if (isCategoriesShorthand(item as SidebarItemConfig)) {
+    Object.values(item as SidebarCategoriesShorthand).forEach((category) =>
+      category.forEach(validateSidebarItem),
+    );
+  } else {
+    Joi.assert(item, sidebarItemSchema);
+    if ((item as SidebarItemCategoryConfig).type === 'category') {
+      (item as SidebarItemCategoryConfig).items.forEach(validateSidebarItem);
+    }
+  }
+}
+
+export function validateSidebars(
+  sidebars: unknown,
+): asserts sidebars is SidebarsConfig {
+  Object.values(sidebars as SidebarsConfig).forEach((sidebar) => {
+    if (Array.isArray(sidebar)) {
+      sidebar.forEach(validateSidebarItem);
+    } else {
+      validateSidebarItem(sidebar);
+    }
+  });
+}

package/src/translations.ts

@@ -5,20 +5,15 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import {
-  LoadedVersion,
-  Sidebar,
-  LoadedContent,
-  Sidebars,
-  SidebarItem,
-} from './types';
-
-import {chain, mapValues, flatten, keyBy} from 'lodash';
+import type {LoadedVersion, LoadedContent} from './types';
+import type {Sidebar, Sidebars} from './sidebars/types';
+
+import {chain, mapValues, keyBy} from 'lodash';
 import {
   collectSidebarCategories,
   transformSidebarItems,
   collectSidebarLinks,
-} from './sidebars';
+} from './sidebars/utils';
 import {
   TranslationFileContent,
   TranslationFile,
@@ -131,7 +126,7 @@ function translateSidebar({
   sidebarName: string;
   sidebarsTranslations: TranslationFileContent;
 }): Sidebar {
-  return transformSidebarItems(sidebar, (item: SidebarItem): SidebarItem => {
+  return transformSidebarItems(sidebar, (item) => {
     if (item.type === 'category') {
       return {
         ...item,
@@ -222,7 +217,7 @@ function translateVersion(
 function getVersionsTranslationFiles(
   versions: LoadedVersion[],
 ): TranslationFiles {
-  return flatten(versions.map(getVersionTranslationFiles));
+  return versions.flatMap(getVersionTranslationFiles);
 }
 function translateVersions(
   versions: LoadedVersion[],

package/src/types.ts

@@ -13,6 +13,7 @@ import type {
   BrokenMarkdownLink as IBrokenMarkdownLink,
   ContentPaths,
 } from '@docusaurus/utils/lib/markdownLinks';
+import type {SidebarItemsGeneratorOption, Sidebars} from './sidebars/types';
 
 export type DocFile = {
   contentPath: string; // /!\ may be localized
@@ -104,100 +105,6 @@ export type PluginOptions = MetadataOptions &
     tagsBasePath: string;
   };
 
-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 SidebarItemCategory = SidebarItemBase & {
-  type: 'category';
-  label: string;
-  items: SidebarItem[];
-  collapsed: boolean;
-  collapsible: boolean;
-};
-
-export type UnprocessedSidebarItemAutogenerated = {
-  type: 'autogenerated';
-  dirName: string;
-};
-
-export type UnprocessedSidebarItemCategory = SidebarItemBase & {
-  type: 'category';
-  label: string;
-  items: UnprocessedSidebarItem[];
-  collapsed: boolean;
-  collapsible: boolean;
-};
-
-export type UnprocessedSidebarItem =
-  | SidebarItemDoc
-  | SidebarItemLink
-  | UnprocessedSidebarItemCategory
-  | UnprocessedSidebarItemAutogenerated;
-
-export type UnprocessedSidebar = UnprocessedSidebarItem[];
-export type UnprocessedSidebars = Record<string, UnprocessedSidebar>;
-
-export type SidebarItem =
-  | SidebarItemDoc
-  | SidebarItemLink
-  | SidebarItemCategory;
-
-export type Sidebar = SidebarItem[];
-export type SidebarItemType = SidebarItem['type'];
-export type Sidebars = Record<string, Sidebar>;
-
-// 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: UnprocessedSidebarItemAutogenerated;
-  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[]>;
-
-export type OrderMetadata = {
-  previous?: string;
-  next?: string;
-  sidebar?: string;
-};
-
 export type LastUpdateData = {
   lastUpdatedAt?: number;
   formattedLastUpdatedAt?: string;

package/lib/sidebarItemsGenerator.js

@@ -1,222 +0,0 @@
-"use strict";
-/**
- * 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.
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.DefaultSidebarItemsGenerator = exports.CategoryMetadataFilenamePattern = exports.CategoryMetadataFilenameBase = void 0;
-const tslib_1 = require("tslib");
-const lodash_1 = require("lodash");
-const utils_1 = require("@docusaurus/utils");
-const utils_validation_1 = require("@docusaurus/utils-validation");
-const chalk_1 = (0, tslib_1.__importDefault)(require("chalk"));
-const path_1 = (0, tslib_1.__importDefault)(require("path"));
-const fs_extra_1 = (0, tslib_1.__importDefault)(require("fs-extra"));
-const js_yaml_1 = (0, tslib_1.__importDefault)(require("js-yaml"));
-const BreadcrumbSeparator = '/';
-exports.CategoryMetadataFilenameBase = '_category_';
-exports.CategoryMetadataFilenamePattern = '_category_.{json,yml,yaml}';
-const CategoryMetadatasFileSchema = utils_validation_1.Joi.object({
-    label: utils_validation_1.Joi.string(),
-    position: utils_validation_1.Joi.number(),
-    collapsed: utils_validation_1.Joi.boolean(),
-    collapsible: utils_validation_1.Joi.boolean(),
-    className: utils_validation_1.Joi.string(),
-});
-// 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/index.md`, we may want to read the metadata as yaml on it
-// see https://github.com/facebook/docusaurus/issues/3464#issuecomment-818670449
-async function readCategoryMetadatasFile(categoryDirPath) {
-    var _a, _b;
-    function validateCategoryMetadataFile(content) {
-        return utils_validation_1.Joi.attempt(content, CategoryMetadatasFileSchema);
-    }
-    async function tryReadFile(fileNameWithExtension, parse) {
-        // Simpler to use only posix paths for mocking file metadatas in tests
-        const filePath = (0, utils_1.posixPath)(path_1.default.join(categoryDirPath, fileNameWithExtension));
-        if (await fs_extra_1.default.pathExists(filePath)) {
-            const contentString = await fs_extra_1.default.readFile(filePath, { encoding: 'utf8' });
-            const unsafeContent = parse(contentString);
-            try {
-                return validateCategoryMetadataFile(unsafeContent);
-            }
-            catch (e) {
-                console.error(chalk_1.default.red(`The docs sidebar category metadata file looks invalid!\nPath: ${filePath}`));
-                throw e;
-            }
-        }
-        return null;
-    }
-    return ((_b = (_a = (await tryReadFile(`${exports.CategoryMetadataFilenameBase}.json`, JSON.parse))) !== null && _a !== void 0 ? _a : (await tryReadFile(`${exports.CategoryMetadataFilenameBase}.yml`, js_yaml_1.default.load))) !== null && _b !== void 0 ? _b : 
-    // eslint-disable-next-line no-return-await
-    (await tryReadFile(`${exports.CategoryMetadataFilenameBase}.yaml`, js_yaml_1.default.load)));
-}
-// [...parents, tail]
-function parseBreadcrumb(breadcrumb) {
-    return {
-        parents: (0, lodash_1.take)(breadcrumb, breadcrumb.length - 1),
-        tail: (0, lodash_1.last)(breadcrumb),
-    };
-}
-// Comment for this feature: https://github.com/facebook/docusaurus/issues/3464#issuecomment-818670449
-const DefaultSidebarItemsGenerator = async ({ item, docs: allDocs, version, numberPrefixParser, options, }) => {
-    // Doc at the root of the autogenerated sidebar dir
-    function isRootDoc(doc) {
-        return doc.sourceDirName === item.dirName;
-    }
-    // Doc inside a subfolder of the autogenerated sidebar dir
-    function isCategoryDoc(doc) {
-        if (isRootDoc(doc)) {
-            return false;
-        }
-        return (
-        // autogen dir is . and doc is in subfolder
-        item.dirName === '.' ||
-            // autogen dir is not . and doc is in subfolder
-            // "api/myDoc" startsWith "api/" (note "api2/myDoc" is not included)
-            doc.sourceDirName.startsWith((0, utils_1.addTrailingSlash)(item.dirName)));
-    }
-    function isInAutogeneratedDir(doc) {
-        return isRootDoc(doc) || isCategoryDoc(doc);
-    }
-    // autogenDir=a/b and docDir=a/b/c/d => returns c/d
-    // autogenDir=a/b and docDir=a/b => returns .
-    function getDocDirRelativeToAutogenDir(doc) {
-        if (!isInAutogeneratedDir(doc)) {
-            throw new Error('getDocDirRelativeToAutogenDir() can only be called for subdocs of the sidebar autogen dir.');
-        }
-        // Is there a node API to compare 2 relative paths more easily?
-        // path.relative() does not give good results
-        if (item.dirName === '.') {
-            return doc.sourceDirName;
-        }
-        else if (item.dirName === doc.sourceDirName) {
-            return '.';
-        }
-        else {
-            return doc.sourceDirName.replace((0, utils_1.addTrailingSlash)(item.dirName), '');
-        }
-    }
-    // Get only docs in the autogen dir
-    // Sort by folder+filename at once
-    const docs = (0, lodash_1.sortBy)(allDocs.filter(isInAutogeneratedDir), (d) => d.source);
-    if (docs.length === 0) {
-        console.warn(chalk_1.default.yellow(`No docs found in dir ${item.dirName}: can't auto-generate a sidebar.`));
-    }
-    function createDocSidebarItem(doc) {
-        return {
-            type: 'doc',
-            id: doc.id,
-            ...(doc.frontMatter.sidebar_label && {
-                label: doc.frontMatter.sidebar_label,
-            }),
-            ...(doc.frontMatter.sidebar_class_name && {
-                className: doc.frontMatter.sidebar_class_name,
-            }),
-            ...(typeof doc.sidebarPosition !== 'undefined' && {
-                position: doc.sidebarPosition,
-            }),
-        };
-    }
-    async function createCategorySidebarItem({ breadcrumb, }) {
-        var _a, _b, _c, _d;
-        const categoryDirPath = path_1.default.join(version.contentPath, item.dirName, // fix https://github.com/facebook/docusaurus/issues/4638
-        breadcrumb.join(BreadcrumbSeparator));
-        const categoryMetadatas = await readCategoryMetadatasFile(categoryDirPath);
-        const { tail } = parseBreadcrumb(breadcrumb);
-        const { filename, numberPrefix } = numberPrefixParser(tail);
-        const position = (_a = categoryMetadatas === null || categoryMetadatas === void 0 ? void 0 : categoryMetadatas.position) !== null && _a !== void 0 ? _a : numberPrefix;
-        const collapsible = (_b = categoryMetadatas === null || categoryMetadatas === void 0 ? void 0 : categoryMetadatas.collapsible) !== null && _b !== void 0 ? _b : options.sidebarCollapsible;
-        const collapsed = (_c = categoryMetadatas === null || categoryMetadatas === void 0 ? void 0 : categoryMetadatas.collapsed) !== null && _c !== void 0 ? _c : options.sidebarCollapsed;
-        const className = categoryMetadatas === null || categoryMetadatas === void 0 ? void 0 : categoryMetadatas.className;
-        return {
-            type: 'category',
-            label: (_d = categoryMetadatas === null || categoryMetadatas === void 0 ? void 0 : categoryMetadatas.label) !== null && _d !== void 0 ? _d : filename,
-            items: [],
-            collapsed,
-            collapsible,
-            ...(typeof position !== 'undefined' && { position }),
-            ...(typeof className !== 'undefined' && { className }),
-        };
-    }
-    // Not sure how to simplify this algorithm :/
-    async function autogenerateSidebarItems() {
-        const sidebarItems = []; // mutable result
-        const categoriesByBreadcrumb = {}; // mutable cache of categories already created
-        async function getOrCreateCategoriesForBreadcrumb(breadcrumb) {
-            if (breadcrumb.length === 0) {
-                return null;
-            }
-            const { parents } = parseBreadcrumb(breadcrumb);
-            const parentCategory = await getOrCreateCategoriesForBreadcrumb(parents);
-            const existingCategory = categoriesByBreadcrumb[breadcrumb.join(BreadcrumbSeparator)];
-            if (existingCategory) {
-                return existingCategory;
-            }
-            else {
-                const newCategory = await createCategorySidebarItem({
-                    breadcrumb,
-                });
-                if (parentCategory) {
-                    parentCategory.items.push(newCategory);
-                }
-                else {
-                    sidebarItems.push(newCategory);
-                }
-                categoriesByBreadcrumb[breadcrumb.join(BreadcrumbSeparator)] =
-                    newCategory;
-                return newCategory;
-            }
-        }
-        // Get the category breadcrumb of a doc (relative to the dir of the autogenerated sidebar item)
-        function getRelativeBreadcrumb(doc) {
-            const relativeDirPath = getDocDirRelativeToAutogenDir(doc);
-            if (relativeDirPath === '.') {
-                return [];
-            }
-            else {
-                return relativeDirPath.split(BreadcrumbSeparator);
-            }
-        }
-        async function handleDocItem(doc) {
-            const breadcrumb = getRelativeBreadcrumb(doc);
-            const category = await getOrCreateCategoriesForBreadcrumb(breadcrumb);
-            const docSidebarItem = createDocSidebarItem(doc);
-            if (category) {
-                category.items.push(docSidebarItem);
-            }
-            else {
-                sidebarItems.push(docSidebarItem);
-            }
-        }
-        // async process made sequential on purpose! order matters
-        // eslint-disable-next-line no-restricted-syntax
-        for (const doc of docs) {
-            // eslint-disable-next-line no-await-in-loop
-            await handleDocItem(doc);
-        }
-        return sidebarItems;
-    }
-    const sidebarItems = await autogenerateSidebarItems();
-    return sortSidebarItems(sidebarItems);
-};
-exports.DefaultSidebarItemsGenerator = DefaultSidebarItemsGenerator;
-// 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 sortSidebarItems(sidebarItems) {
-    const processedSidebarItems = sidebarItems.map((item) => {
-        if (item.type === 'category') {
-            return {
-                ...item,
-                items: sortSidebarItems(item.items),
-            };
-        }
-        return item;
-    });
-    const sortedSidebarItems = (0, lodash_1.orderBy)(processedSidebarItems, (item) => item.position, ['asc']);
-    return sortedSidebarItems.map(({ position, ...item }) => item);
-}

package/lib/sidebars.d.ts

@@ -1,45 +0,0 @@
-/**
- * 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 { Sidebars, SidebarItem, SidebarItemLink, SidebarItemDoc, Sidebar, SidebarItemCategory, UnprocessedSidebars, UnprocessedSidebar, DocMetadataBase, VersionMetadata, SidebarItemsGeneratorDoc, SidebarItemsGeneratorVersion, NumberPrefixParser, SidebarItemsGeneratorOption, SidebarOptions, PluginOptions } from './types';
-export declare const DefaultSidebars: UnprocessedSidebars;
-export declare const DisabledSidebars: UnprocessedSidebars;
-export declare function resolveSidebarPathOption(siteDir: string, sidebarPathOption: PluginOptions['sidebarPath']): PluginOptions['sidebarPath'];
-export declare function loadSidebars(sidebarFilePath: string | false | undefined, options: SidebarOptions): UnprocessedSidebars;
-export declare function toSidebarItemsGeneratorDoc(doc: DocMetadataBase): SidebarItemsGeneratorDoc;
-export declare function toSidebarItemsGeneratorVersion(version: VersionMetadata): SidebarItemsGeneratorVersion;
-export declare function fixSidebarItemInconsistencies(item: SidebarItem): SidebarItem;
-export declare function processSidebar({ sidebarItemsGenerator, numberPrefixParser, unprocessedSidebar, docs, version, options, }: {
-    sidebarItemsGenerator: SidebarItemsGeneratorOption;
-    numberPrefixParser: NumberPrefixParser;
-    unprocessedSidebar: UnprocessedSidebar;
-    docs: DocMetadataBase[];
-    version: VersionMetadata;
-    options: SidebarOptions;
-}): Promise<Sidebar>;
-export declare function processSidebars({ sidebarItemsGenerator, numberPrefixParser, unprocessedSidebars, docs, version, options, }: {
-    sidebarItemsGenerator: SidebarItemsGeneratorOption;
-    numberPrefixParser: NumberPrefixParser;
-    unprocessedSidebars: UnprocessedSidebars;
-    docs: DocMetadataBase[];
-    version: VersionMetadata;
-    options: SidebarOptions;
-}): Promise<Sidebars>;
-export declare function collectSidebarDocItems(sidebar: Sidebar): SidebarItemDoc[];
-export declare function collectSidebarCategories(sidebar: Sidebar): SidebarItemCategory[];
-export declare function collectSidebarLinks(sidebar: Sidebar): SidebarItemLink[];
-export declare function transformSidebarItems(sidebar: Sidebar, updateFn: (item: SidebarItem) => SidebarItem): Sidebar;
-export declare function collectSidebarsDocIds(sidebars: Sidebars): Record<string, string[]>;
-export declare 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;
-};