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

package/lib/sidebars.d.ts

@@ -1,43 +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, PluginOptions } from './types';
-export declare const DefaultCategoryCollapsedValue = true;
-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): UnprocessedSidebars;
-export declare function toSidebarItemsGeneratorDoc(doc: DocMetadataBase): SidebarItemsGeneratorDoc;
-export declare function toSidebarItemsGeneratorVersion(version: VersionMetadata): SidebarItemsGeneratorVersion;
-export declare function processSidebar({ sidebarItemsGenerator, numberPrefixParser, unprocessedSidebar, docs, version, }: {
-    sidebarItemsGenerator: SidebarItemsGeneratorOption;
-    numberPrefixParser: NumberPrefixParser;
-    unprocessedSidebar: UnprocessedSidebar;
-    docs: DocMetadataBase[];
-    version: VersionMetadata;
-}): Promise<Sidebar>;
-export declare function processSidebars({ sidebarItemsGenerator, numberPrefixParser, unprocessedSidebars, docs, version, }: {
-    sidebarItemsGenerator: SidebarItemsGeneratorOption;
-    numberPrefixParser: NumberPrefixParser;
-    unprocessedSidebars: UnprocessedSidebars;
-    docs: DocMetadataBase[];
-    version: VersionMetadata;
-}): 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;
-};

package/lib/sidebars.js

@@ -1,319 +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.createSidebarsUtils = exports.collectSidebarsDocIds = exports.transformSidebarItems = exports.collectSidebarLinks = exports.collectSidebarCategories = exports.collectSidebarDocItems = exports.processSidebars = exports.processSidebar = exports.toSidebarItemsGeneratorVersion = exports.toSidebarItemsGeneratorDoc = exports.loadSidebars = exports.resolveSidebarPathOption = exports.DisabledSidebars = exports.DefaultSidebars = exports.DefaultCategoryCollapsedValue = void 0;
-const tslib_1 = require("tslib");
-const fs_extra_1 = tslib_1.__importDefault(require("fs-extra"));
-const import_fresh_1 = tslib_1.__importDefault(require("import-fresh"));
-const lodash_1 = require("lodash");
-const utils_1 = require("@docusaurus/utils");
-const combine_promises_1 = tslib_1.__importDefault(require("combine-promises"));
-const sidebarItemsGenerator_1 = require("./sidebarItemsGenerator");
-const path_1 = tslib_1.__importDefault(require("path"));
-function isCategoryShorthand(item) {
-    return typeof item !== 'string' && !item.type;
-}
-// categories are collapsed by default, unless user set collapsed = false
-exports.DefaultCategoryCollapsedValue = true;
-/**
- * Convert {category1: [item1,item2]} shorthand syntax to long-form syntax
- */
-function normalizeCategoryShorthand(sidebar) {
-    return Object.entries(sidebar).map(([label, items]) => ({
-        type: 'category',
-        collapsed: exports.DefaultCategoryCollapsedValue,
-        label,
-        items,
-    }));
-}
-/**
- * Check that item contains only allowed keys.
- */
-function assertItem(item, keys) {
-    const unknownKeys = Object.keys(item).filter(
-    // @ts-expect-error: key is always string
-    (key) => !keys.includes(key) && key !== 'type');
-    if (unknownKeys.length) {
-        throw new Error(`Unknown sidebar item keys: ${unknownKeys}. Item: ${JSON.stringify(item)}`);
-    }
-}
-function assertIsCategory(item) {
-    assertItem(item, ['items', 'label', 'collapsed', 'customProps']);
-    if (typeof item.label !== 'string') {
-        throw new Error(`Error loading ${JSON.stringify(item)}: "label" must be a string.`);
-    }
-    if (!Array.isArray(item.items)) {
-        throw new Error(`Error loading ${JSON.stringify(item)}: "items" must be an array.`);
-    }
-    // "collapsed" is an optional property
-    if (item.hasOwnProperty('collapsed') && typeof item.collapsed !== 'boolean') {
-        throw new Error(`Error loading ${JSON.stringify(item)}: "collapsed" must be a boolean.`);
-    }
-}
-function assertIsAutogenerated(item) {
-    assertItem(item, ['dirName', 'customProps']);
-    if (typeof item.dirName !== 'string') {
-        throw new Error(`Error loading ${JSON.stringify(item)}: "dirName" must be a string.`);
-    }
-    if (item.dirName.startsWith('/') || item.dirName.endsWith('/')) {
-        throw new Error(`Error loading ${JSON.stringify(item)}: "dirName" must be a dir path relative to the docs folder root, and should not start or end with slash`);
-    }
-}
-function assertIsDoc(item) {
-    assertItem(item, ['id', 'label', 'customProps']);
-    if (typeof item.id !== 'string') {
-        throw new Error(`Error loading ${JSON.stringify(item)}: "id" must be a string.`);
-    }
-    if (item.label && typeof item.label !== 'string') {
-        throw new Error(`Error loading ${JSON.stringify(item)}: "label" must be a string.`);
-    }
-}
-function assertIsLink(item) {
-    assertItem(item, ['href', 'label', 'customProps']);
-    if (typeof item.href !== 'string') {
-        throw new Error(`Error loading ${JSON.stringify(item)}: "href" must be a string.`);
-    }
-    if (typeof item.label !== 'string') {
-        throw new Error(`Error loading ${JSON.stringify(item)}: "label" must be a string.`);
-    }
-}
-/**
- * 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) {
-    if (typeof item === 'string') {
-        return [
-            {
-                type: 'doc',
-                id: item,
-            },
-        ];
-    }
-    if (isCategoryShorthand(item)) {
-        return lodash_1.flatMap(normalizeCategoryShorthand(item), normalizeItem);
-    }
-    switch (item.type) {
-        case 'category':
-            assertIsCategory(item);
-            return [
-                {
-                    collapsed: exports.DefaultCategoryCollapsedValue,
-                    ...item,
-                    items: lodash_1.flatMap(item.items, normalizeItem),
-                },
-            ];
-        case 'autogenerated':
-            assertIsAutogenerated(item);
-            return [item];
-        case 'link':
-            assertIsLink(item);
-            return [item];
-        case 'ref':
-        case 'doc':
-            assertIsDoc(item);
-            return [item];
-        default: {
-            const extraMigrationError = item.type === 'subcategory'
-                ? 'Docusaurus v2: "subcategory" has been renamed as "category".'
-                : '';
-            throw new Error(`Unknown sidebar item type "${item.type}". Sidebar item is ${JSON.stringify(item)}.\n${extraMigrationError}`);
-        }
-    }
-}
-function normalizeSidebar(sidebar) {
-    const normalizedSidebar = Array.isArray(sidebar)
-        ? sidebar
-        : normalizeCategoryShorthand(sidebar);
-    return lodash_1.flatMap(normalizedSidebar, normalizeItem);
-}
-function normalizeSidebars(sidebars) {
-    return lodash_1.mapValues(sidebars, normalizeSidebar);
-}
-exports.DefaultSidebars = {
-    defaultSidebar: [
-        {
-            type: 'autogenerated',
-            dirName: '.',
-        },
-    ],
-};
-exports.DisabledSidebars = {};
-// If a path is provided, make it absolute
-// use this before loadSidebars()
-function resolveSidebarPathOption(siteDir, sidebarPathOption) {
-    return sidebarPathOption
-        ? path_1.default.resolve(siteDir, sidebarPathOption)
-        : sidebarPathOption;
-}
-exports.resolveSidebarPathOption = resolveSidebarPathOption;
-// TODO refactor: make async
-// Note: sidebarFilePath must be absolute, use resolveSidebarPathOption
-function loadSidebars(sidebarFilePath) {
-    // false => no sidebars
-    if (sidebarFilePath === false) {
-        return exports.DisabledSidebars;
-    }
-    // undefined => defaults to autogenerated sidebars
-    if (typeof sidebarFilePath === 'undefined') {
-        return exports.DefaultSidebars;
-    }
-    // unexisting 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_extra_1.default.existsSync(sidebarFilePath)) {
-        return exports.DisabledSidebars;
-    }
-    // We don't want sidebars to be cached because of hot reloading.
-    const sidebarJson = import_fresh_1.default(sidebarFilePath);
-    return normalizeSidebars(sidebarJson);
-}
-exports.loadSidebars = loadSidebars;
-function toSidebarItemsGeneratorDoc(doc) {
-    return lodash_1.pick(doc, [
-        'id',
-        'frontMatter',
-        'source',
-        'sourceDirName',
-        'sidebarPosition',
-    ]);
-}
-exports.toSidebarItemsGeneratorDoc = toSidebarItemsGeneratorDoc;
-function toSidebarItemsGeneratorVersion(version) {
-    return lodash_1.pick(version, ['versionName', 'contentPath']);
-}
-exports.toSidebarItemsGeneratorVersion = toSidebarItemsGeneratorVersion;
-// Handle the generation of autogenerated sidebar items
-async function processSidebar({ sidebarItemsGenerator, numberPrefixParser, unprocessedSidebar, docs, version, }) {
-    // Just a minor lazy transformation optimization
-    const getSidebarItemsGeneratorDocsAndVersion = lodash_1.memoize(() => ({
-        docs: docs.map(toSidebarItemsGeneratorDoc),
-        version: toSidebarItemsGeneratorVersion(version),
-    }));
-    async function processRecursive(item) {
-        if (item.type === 'category') {
-            return [
-                {
-                    ...item,
-                    items: (await Promise.all(item.items.map(processRecursive))).flat(),
-                },
-            ];
-        }
-        if (item.type === 'autogenerated') {
-            return sidebarItemsGenerator({
-                item,
-                numberPrefixParser,
-                defaultSidebarItemsGenerator: sidebarItemsGenerator_1.DefaultSidebarItemsGenerator,
-                ...getSidebarItemsGeneratorDocsAndVersion(),
-            });
-        }
-        return [item];
-    }
-    return (await Promise.all(unprocessedSidebar.map(processRecursive))).flat();
-}
-exports.processSidebar = processSidebar;
-async function processSidebars({ sidebarItemsGenerator, numberPrefixParser, unprocessedSidebars, docs, version, }) {
-    return combine_promises_1.default(lodash_1.mapValues(unprocessedSidebars, (unprocessedSidebar) => processSidebar({
-        sidebarItemsGenerator,
-        numberPrefixParser,
-        unprocessedSidebar,
-        docs,
-        version,
-    })));
-}
-exports.processSidebars = processSidebars;
-function collectSidebarItemsOfType(type, sidebar) {
-    function collectRecursive(item) {
-        const currentItemsCollected = item.type === type ? [item] : [];
-        const childItemsCollected = item.type === 'category' ? lodash_1.flatten(item.items.map(collectRecursive)) : [];
-        return [...currentItemsCollected, ...childItemsCollected];
-    }
-    return lodash_1.flatten(sidebar.map(collectRecursive));
-}
-function collectSidebarDocItems(sidebar) {
-    return collectSidebarItemsOfType('doc', sidebar);
-}
-exports.collectSidebarDocItems = collectSidebarDocItems;
-function collectSidebarCategories(sidebar) {
-    return collectSidebarItemsOfType('category', sidebar);
-}
-exports.collectSidebarCategories = collectSidebarCategories;
-function collectSidebarLinks(sidebar) {
-    return collectSidebarItemsOfType('link', sidebar);
-}
-exports.collectSidebarLinks = collectSidebarLinks;
-function transformSidebarItems(sidebar, updateFn) {
-    function transformRecursive(item) {
-        if (item.type === 'category') {
-            return updateFn({
-                ...item,
-                items: item.items.map(transformRecursive),
-            });
-        }
-        return updateFn(item);
-    }
-    return sidebar.map(transformRecursive);
-}
-exports.transformSidebarItems = transformSidebarItems;
-function collectSidebarsDocIds(sidebars) {
-    return lodash_1.mapValues(sidebars, (sidebar) => {
-        return collectSidebarDocItems(sidebar).map((docItem) => docItem.id);
-    });
-}
-exports.collectSidebarsDocIds = collectSidebarsDocIds;
-function createSidebarsUtils(sidebars) {
-    const sidebarNameToDocIds = collectSidebarsDocIds(sidebars);
-    function getFirstDocIdOfFirstSidebar() {
-        var _a;
-        return (_a = Object.values(sidebarNameToDocIds)[0]) === null || _a === void 0 ? void 0 : _a[0];
-    }
-    function getSidebarNameByDocId(docId) {
-        // TODO lookup speed can be optimized
-        const entry = Object.entries(sidebarNameToDocIds).find(([_sidebarName, docIds]) => docIds.includes(docId));
-        return entry === null || entry === void 0 ? void 0 : entry[0];
-    }
-    function getDocNavigation(docId) {
-        const sidebarName = getSidebarNameByDocId(docId);
-        if (sidebarName) {
-            const docIds = sidebarNameToDocIds[sidebarName];
-            const currentIndex = docIds.indexOf(docId);
-            const { previous, next } = utils_1.getElementsAround(docIds, currentIndex);
-            return {
-                sidebarName,
-                previousId: previous,
-                nextId: next,
-            };
-        }
-        else {
-            return {
-                sidebarName: undefined,
-                previousId: undefined,
-                nextId: undefined,
-            };
-        }
-    }
-    function checkSidebarsDocIds(validDocIds, sidebarFilePath) {
-        const allSidebarDocIds = lodash_1.flatten(Object.values(sidebarNameToDocIds));
-        const invalidSidebarDocIds = lodash_1.difference(allSidebarDocIds, validDocIds);
-        if (invalidSidebarDocIds.length > 0) {
-            throw new Error(`Invalid sidebar file at "${utils_1.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,
-    };
-}
-exports.createSidebarsUtils = createSidebarsUtils;