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

package/lib/sidebars.js

@@ -1,320 +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 (typeof item.collapsed !== 'undefined' &&
-        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;

package/lib/theme/hooks/useDocs.d.ts

@@ -1,20 +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 { GlobalPluginData, GlobalVersion } from '../../types';
-import { ActivePlugin, ActiveDocContext, DocVersionSuggestions, GetActivePluginOptions } from '../../client/docsClientUtils';
-export declare const useAllDocsData: () => Record<string, GlobalPluginData>;
-export declare const useDocsData: (pluginId: string | undefined) => GlobalPluginData;
-export declare const useActivePlugin: (options?: GetActivePluginOptions) => ActivePlugin | undefined;
-export declare const useActivePluginAndVersion: (options?: GetActivePluginOptions) => {
-    activePlugin: ActivePlugin;
-    activeVersion: GlobalVersion | undefined;
-} | undefined;
-export declare const useVersions: (pluginId: string | undefined) => GlobalVersion[];
-export declare const useLatestVersion: (pluginId: string | undefined) => GlobalVersion;
-export declare const useActiveVersion: (pluginId: string | undefined) => GlobalVersion | undefined;
-export declare const useActiveDocContext: (pluginId: string | undefined) => ActiveDocContext;
-export declare const useDocVersionSuggestions: (pluginId: string | undefined) => DocVersionSuggestions;

package/lib/theme/hooks/useDocs.js

@@ -1,75 +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.useDocVersionSuggestions = exports.useActiveDocContext = exports.useActiveVersion = exports.useLatestVersion = exports.useVersions = exports.useActivePluginAndVersion = exports.useActivePlugin = exports.useDocsData = exports.useAllDocsData = void 0;
-const tslib_1 = require("tslib");
-const router_1 = require("@docusaurus/router");
-const useGlobalData_1 = tslib_1.__importStar(require("@docusaurus/useGlobalData"));
-const docsClientUtils_1 = require("../../client/docsClientUtils");
-// Important to use a constant object to avoid React useEffect executions etc...,
-// see https://github.com/facebook/docusaurus/issues/5089
-const StableEmptyObject = {};
-// Not using useAllPluginInstancesData() because in blog-only mode, docs hooks are still used by the theme
-// We need a fail-safe fallback when the docs plugin is not in use
-const useAllDocsData = () => { var _a; 
-// useAllPluginInstancesData('docusaurus-plugin-content-docs');
-return (_a = useGlobalData_1.default()['docusaurus-plugin-content-docs']) !== null && _a !== void 0 ? _a : StableEmptyObject; };
-exports.useAllDocsData = useAllDocsData;
-const useDocsData = (pluginId) => useGlobalData_1.usePluginData('docusaurus-plugin-content-docs', pluginId);
-exports.useDocsData = useDocsData;
-const useActivePlugin = (options = {}) => {
-    const data = exports.useAllDocsData();
-    const { pathname } = router_1.useLocation();
-    return docsClientUtils_1.getActivePlugin(data, pathname, options);
-};
-exports.useActivePlugin = useActivePlugin;
-const useActivePluginAndVersion = (options = {}) => {
-    const activePlugin = exports.useActivePlugin(options);
-    const { pathname } = router_1.useLocation();
-    if (activePlugin) {
-        const activeVersion = docsClientUtils_1.getActiveVersion(activePlugin.pluginData, pathname);
-        return {
-            activePlugin,
-            activeVersion,
-        };
-    }
-    return undefined;
-};
-exports.useActivePluginAndVersion = useActivePluginAndVersion;
-// versions are returned ordered (most recent first)
-const useVersions = (pluginId) => {
-    const data = exports.useDocsData(pluginId);
-    return data.versions;
-};
-exports.useVersions = useVersions;
-const useLatestVersion = (pluginId) => {
-    const data = exports.useDocsData(pluginId);
-    return docsClientUtils_1.getLatestVersion(data);
-};
-exports.useLatestVersion = useLatestVersion;
-// Note: return undefined on doc-unrelated pages,
-// because there's no version currently considered as active
-const useActiveVersion = (pluginId) => {
-    const data = exports.useDocsData(pluginId);
-    const { pathname } = router_1.useLocation();
-    return docsClientUtils_1.getActiveVersion(data, pathname);
-};
-exports.useActiveVersion = useActiveVersion;
-const useActiveDocContext = (pluginId) => {
-    const data = exports.useDocsData(pluginId);
-    const { pathname } = router_1.useLocation();
-    return docsClientUtils_1.getActiveDocContext(data, pathname);
-};
-exports.useActiveDocContext = useActiveDocContext;
-// Useful to say "hey, you are not on the latest docs version, please switch"
-const useDocVersionSuggestions = (pluginId) => {
-    const data = exports.useDocsData(pluginId);
-    const { pathname } = router_1.useLocation();
-    return docsClientUtils_1.getDocVersionSuggestions(data, pathname);
-};
-exports.useDocVersionSuggestions = useDocVersionSuggestions;

package/lib/versions.d.ts

@@ -1,16 +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 { PluginOptions, VersionMetadata } from './types';
-import { LoadContext } from '@docusaurus/types';
-export declare function getVersionedDocsDirPath(siteDir: string, pluginId: string): string;
-export declare function getVersionedSidebarsDirPath(siteDir: string, pluginId: string): string;
-export declare function getVersionsFilePath(siteDir: string, pluginId: string): string;
-export declare function readVersionsMetadata({ context, options, }: {
-    context: Pick<LoadContext, 'siteDir' | 'baseUrl' | 'i18n'>;
-    options: Pick<PluginOptions, 'id' | 'path' | 'sidebarPath' | 'routeBasePath' | 'includeCurrentVersion' | 'disableVersioning' | 'lastVersion' | 'versions' | 'onlyIncludeVersions' | 'editUrl' | 'editCurrentVersion'>;
-}): VersionMetadata[];
-export declare function getDocsDirPaths(versionMetadata: Pick<VersionMetadata, 'contentPath' | 'contentPathLocalized'>): [string, string];