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

package/lib/sidebars/postProcessor.js

@@ -0,0 +1,82 @@
+"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.postProcessSidebars = postProcessSidebars;
+const tslib_1 = require("tslib");
+const lodash_1 = tslib_1.__importDefault(require("lodash"));
+const utils_1 = require("@docusaurus/utils");
+function normalizeCategoryLink(category, params) {
+    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 = (0, utils_1.normalizeUrl)([params.version.path, slug]);
+        return {
+            ...category.link,
+            slug,
+            permalink,
+        };
+    }
+    return category.link;
+}
+function postProcessSidebarItem(item, params) {
+    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) => 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;
+}
+function postProcessSidebars(sidebars, params) {
+    const draftIds = new Set(params.drafts.map((d) => d.id));
+    return lodash_1.default.mapValues(sidebars, (sidebar) => sidebar
+        .map((item) => postProcessSidebarItem(item, { ...params, draftIds }))
+        .filter((v) => Boolean(v)));
+}

package/lib/sidebars/processor.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 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 { NormalizedSidebars, ProcessedSidebars, SidebarProcessorParams, CategoryMetadataFile } from './types';
+export declare function processSidebars(unprocessedSidebars: NormalizedSidebars, categoriesMetadata: {
+    [filePath: string]: CategoryMetadataFile;
+}, params: SidebarProcessorParams): Promise<ProcessedSidebars>;

package/lib/sidebars/processor.js

@@ -0,0 +1,77 @@
+"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.processSidebars = processSidebars;
+const tslib_1 = require("tslib");
+const lodash_1 = tslib_1.__importDefault(require("lodash"));
+const combine_promises_1 = tslib_1.__importDefault(require("combine-promises"));
+const generator_1 = require("./generator");
+const validation_1 = require("./validation");
+const docs_1 = require("../docs");
+function toSidebarItemsGeneratorDoc(doc) {
+    return lodash_1.default.pick(doc, [
+        'id',
+        'title',
+        'frontMatter',
+        'source',
+        'sourceDirName',
+        'sidebarPosition',
+    ]);
+}
+function toSidebarItemsGeneratorVersion(version) {
+    return lodash_1.default.pick(version, ['versionName', 'contentPath']);
+}
+// Handle the generation of autogenerated sidebar items and other
+// post-processing checks
+async function processSidebar(unprocessedSidebar, categoriesMetadata, params) {
+    const { sidebarItemsGenerator, numberPrefixParser, docs, version } = params;
+    // Just a minor lazy transformation optimization
+    const getSidebarItemsGeneratorDocsAndVersion = lodash_1.default.memoize(() => ({
+        docs: docs.map(toSidebarItemsGeneratorDoc),
+        version: toSidebarItemsGeneratorVersion(version),
+    }));
+    async function processAutoGeneratedItem(item) {
+        const generatedItems = await sidebarItemsGenerator({
+            item,
+            numberPrefixParser,
+            defaultSidebarItemsGenerator: generator_1.DefaultSidebarItemsGenerator,
+            isCategoryIndex: docs_1.isCategoryIndex,
+            ...getSidebarItemsGeneratorDocsAndVersion(),
+            categoriesMetadata,
+        });
+        // Process again... weird but sidebar item generated might generate some
+        // auto-generated items?
+        // TODO repeatedly process & unwrap autogenerated items until there are no
+        // more autogenerated items, or when loop count (e.g. 10) is reached
+        return processItems(generatedItems);
+    }
+    async function processItem(item) {
+        if (item.type === 'category') {
+            return [
+                {
+                    ...item,
+                    items: (await Promise.all(item.items.map(processItem))).flat(),
+                },
+            ];
+        }
+        if (item.type === 'autogenerated') {
+            return processAutoGeneratedItem(item);
+        }
+        return [item];
+    }
+    async function processItems(items) {
+        return (await Promise.all(items.map(processItem))).flat();
+    }
+    const processedSidebar = await processItems(unprocessedSidebar);
+    return processedSidebar;
+}
+async function processSidebars(unprocessedSidebars, categoriesMetadata, params) {
+    const processedSidebars = await (0, combine_promises_1.default)(lodash_1.default.mapValues(unprocessedSidebars, (unprocessedSidebar) => processSidebar(unprocessedSidebar, categoriesMetadata, params)));
+    (0, validation_1.validateSidebars)(processedSidebars);
+    return processedSidebars;
+}

package/lib/sidebars/types.d.ts

@@ -0,0 +1,192 @@
+/**
+ * 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 { Optional, Required } from 'utility-types';
+import type { NumberPrefixParser, SidebarOptions, CategoryIndexMatcher, DocMetadataBase, VersionMetadata } from '@docusaurus/plugin-content-docs';
+import type { Slugger } from '@docusaurus/utils';
+type Expand<T extends {
+    [x: string]: unknown;
+}> = {
+    [P in keyof T]: T[P];
+};
+export type SidebarItemBase = {
+    key?: string;
+    className?: string;
+    customProps?: {
+        [key: string]: unknown;
+    };
+};
+export type SidebarItemDoc = SidebarItemBase & {
+    type: 'doc' | 'ref';
+    label?: string;
+    id: string;
+    /**
+     * This is an internal marker set during the sidebar normalization process.
+     * Docs with labels defined in the config need to be translated with JSON.
+     * Otherwise, it's preferable to translate the MDX doc title or front matter.
+     */
+    translatable?: true;
+};
+export type SidebarItemHtml = SidebarItemBase & {
+    type: 'html';
+    value: string;
+    defaultStyle?: boolean;
+};
+export type SidebarItemLink = SidebarItemBase & {
+    type: 'link';
+    href: string;
+    label: string;
+    autoAddBaseUrl?: boolean;
+    description?: string;
+};
+export type SidebarItemAutogenerated = SidebarItemBase & {
+    type: 'autogenerated';
+    dirName: string;
+};
+type SidebarItemCategoryBase = SidebarItemBase & {
+    type: 'category';
+    label: string;
+    collapsed: boolean;
+    collapsible: boolean;
+    description?: string;
+};
+export type SidebarItemCategoryLinkDoc = {
+    type: 'doc';
+    id: string;
+};
+export type SidebarItemCategoryLinkGeneratedIndexConfig = {
+    type: 'generated-index';
+    slug?: string;
+    title?: string;
+    description?: string;
+    image?: string;
+    keywords?: string | readonly string[];
+};
+export type SidebarItemCategoryLinkGeneratedIndex = {
+    type: 'generated-index';
+    slug: string;
+    permalink: string;
+    title?: string;
+    description?: string;
+    image?: string;
+    keywords?: string | readonly string[];
+};
+export type SidebarItemCategoryLinkConfig = SidebarItemCategoryLinkDoc | SidebarItemCategoryLinkGeneratedIndexConfig;
+export type SidebarItemCategoryLink = SidebarItemCategoryLinkDoc | SidebarItemCategoryLinkGeneratedIndex;
+export type SidebarItemCategoryConfig = Expand<Optional<SidebarItemCategoryBase, 'collapsed' | 'collapsible'> & {
+    items: SidebarCategoriesShorthand | SidebarItemConfig[];
+    link?: SidebarItemCategoryLinkConfig;
+}>;
+export type SidebarCategoriesShorthand = {
+    [sidebarCategory: string]: SidebarCategoriesShorthand | SidebarItemConfig[];
+};
+export type SidebarItemConfig = Omit<SidebarItemDoc, 'translatable'> | SidebarItemHtml | SidebarItemLink | SidebarItemAutogenerated | SidebarItemCategoryConfig | string | SidebarCategoriesShorthand;
+export type SidebarConfig = SidebarCategoriesShorthand | SidebarItemConfig[];
+export type SidebarsConfig = {
+    [sidebarId: string]: SidebarConfig;
+};
+export type NormalizedSidebarItemCategory = Expand<Optional<SidebarItemCategoryBase, 'collapsed' | 'collapsible'> & {
+    items: NormalizedSidebarItem[];
+    link?: SidebarItemCategoryLinkConfig;
+}>;
+export type NormalizedSidebarItem = SidebarItemDoc | SidebarItemHtml | SidebarItemLink | NormalizedSidebarItemCategory | SidebarItemAutogenerated;
+export type NormalizedSidebar = NormalizedSidebarItem[];
+export type NormalizedSidebars = {
+    [sidebarId: string]: NormalizedSidebar;
+};
+export type ProcessedSidebarItemCategory = Expand<Optional<SidebarItemCategoryBase, 'collapsed' | 'collapsible'> & {
+    items: ProcessedSidebarItem[];
+    link?: SidebarItemCategoryLinkConfig;
+}>;
+export type ProcessedSidebarItem = SidebarItemDoc | SidebarItemHtml | SidebarItemLink | ProcessedSidebarItemCategory;
+export type ProcessedSidebar = ProcessedSidebarItem[];
+export type ProcessedSidebars = {
+    [sidebarId: string]: ProcessedSidebar;
+};
+export type SidebarItemCategory = Expand<SidebarItemCategoryBase & {
+    items: SidebarItem[];
+    link?: SidebarItemCategoryLink;
+}>;
+export type SidebarItemCategoryWithLink = Required<SidebarItemCategory, 'link'>;
+export type SidebarItemCategoryWithGeneratedIndex = SidebarItemCategoryWithLink & {
+    link: SidebarItemCategoryLinkGeneratedIndex;
+};
+export type SidebarItem = SidebarItemDoc | SidebarItemHtml | SidebarItemLink | SidebarItemCategory;
+export type SidebarNavigationItem = SidebarItemDoc | SidebarItemCategoryWithLink;
+export type Sidebar = SidebarItem[];
+export type SidebarItemType = SidebarItem['type'];
+export type Sidebars = {
+    [sidebarId: string]: Sidebar;
+};
+export type PropSidebarItemCategory = Expand<SidebarItemCategoryBase & {
+    items: PropSidebarItem[];
+    href?: string;
+    linkUnlisted?: boolean;
+}>;
+export type PropSidebarItemLink = SidebarItemLink & {
+    docId?: string;
+    unlisted?: boolean;
+};
+export type PropSidebarItemHtml = SidebarItemHtml;
+export type PropSidebarItem = PropSidebarItemLink | PropSidebarItemCategory | PropSidebarItemHtml;
+export type PropSidebar = PropSidebarItem[];
+export type PropSidebars = {
+    [sidebarId: string]: PropSidebar;
+};
+export type PropSidebarBreadcrumbsItem = PropSidebarItemLink | PropSidebarItemCategory;
+export type CategoryMetadataFile = {
+    key?: string;
+    label?: string;
+    position?: number;
+    description?: string;
+    collapsed?: boolean;
+    collapsible?: boolean;
+    className?: string;
+    link?: SidebarItemCategoryLinkConfig | null;
+    customProps?: {
+        [key: string]: unknown;
+    };
+};
+export type SidebarItemsGeneratorDoc = Pick<DocMetadataBase, 'id' | 'title' | 'frontMatter' | 'source' | 'sourceDirName' | 'sidebarPosition'>;
+export type SidebarItemsGeneratorVersion = Pick<VersionMetadata, 'versionName' | 'contentPath'>;
+export type SidebarItemsGeneratorArgs = {
+    /** The sidebar item with type "autogenerated" to be transformed. */
+    item: SidebarItemAutogenerated;
+    /** Useful metadata for the version this sidebar belongs to. */
+    version: SidebarItemsGeneratorVersion;
+    /** All the docs of that version (unfiltered). */
+    docs: SidebarItemsGeneratorDoc[];
+    /** Number prefix parser configured for this plugin. */
+    numberPrefixParser: NumberPrefixParser;
+    /** The default category index matcher which you can override. */
+    isCategoryIndex: CategoryIndexMatcher;
+    /**
+     * Key is the path relative to the doc content directory, value is the
+     * category metadata file's content.
+     */
+    categoriesMetadata: {
+        [filePath: string]: CategoryMetadataFile;
+    };
+};
+export type SidebarItemsGenerator = (generatorArgs: SidebarItemsGeneratorArgs) => NormalizedSidebar | Promise<NormalizedSidebar>;
+export type SidebarItemsGeneratorOption = (generatorArgs: {
+    /**
+     * Useful to re-use/enhance the default sidebar generation logic from
+     * Docusaurus.
+     * @see https://github.com/facebook/docusaurus/issues/4640#issuecomment-822292320
+     */
+    defaultSidebarItemsGenerator: SidebarItemsGenerator;
+} & SidebarItemsGeneratorArgs) => NormalizedSidebar | Promise<NormalizedSidebar>;
+export type SidebarProcessorParams = {
+    sidebarItemsGenerator: SidebarItemsGeneratorOption;
+    numberPrefixParser: NumberPrefixParser;
+    docs: DocMetadataBase[];
+    drafts: DocMetadataBase[];
+    version: VersionMetadata;
+    categoryLabelSlugger: Slugger;
+    sidebarOptions: SidebarOptions;
+};
+export {};

package/lib/sidebars/types.js

@@ -0,0 +1,8 @@
+"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 });

package/lib/sidebars/utils.d.ts

@@ -0,0 +1,69 @@
+/**
+ * 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 { Sidebars, Sidebar, SidebarItem, SidebarItemCategory, SidebarItemLink, SidebarItemDoc, SidebarCategoriesShorthand, SidebarItemConfig, SidebarItemCategoryWithGeneratedIndex, SidebarNavigationItem } from './types';
+import type { DocMetadataBase, PropNavigationLink, VersionMetadata } from '@docusaurus/plugin-content-docs';
+export declare function isCategoriesShorthand(item: SidebarItemConfig): item is SidebarCategoriesShorthand;
+export declare function transformSidebarItems(sidebar: Sidebar, updateFn: (item: SidebarItem) => SidebarItem): Sidebar;
+export declare function collectSidebarDocItems(sidebar: Sidebar): SidebarItemDoc[];
+export declare function collectSidebarCategories(sidebar: Sidebar): SidebarItemCategory[];
+export declare function collectSidebarLinks(sidebar: Sidebar): SidebarItemLink[];
+export declare function collectSidebarRefs(sidebar: Sidebar): SidebarItemDoc[];
+export declare function collectSidebarDocIds(sidebar: Sidebar): string[];
+export declare function collectSidebarNavigation(sidebar: Sidebar): SidebarNavigationItem[];
+export declare function collectSidebarsDocIds(sidebars: Sidebars): {
+    [sidebarId: string]: string[];
+};
+export declare function collectSidebarsNavigations(sidebars: Sidebars): {
+    [sidebarId: string]: SidebarNavigationItem[];
+};
+export type SidebarNavigation = {
+    sidebarName: string | undefined;
+    previous: SidebarNavigationItem | undefined;
+    next: SidebarNavigationItem | undefined;
+};
+export type SidebarsUtils = {
+    sidebars: Sidebars;
+    getFirstDocIdOfFirstSidebar: () => string | undefined;
+    getSidebarNameByDocId: (docId: string) => string | undefined;
+    getDocNavigation: (params: {
+        docId: string;
+        displayedSidebar: string | null | undefined;
+        unlistedIds: Set<string>;
+    }) => SidebarNavigation;
+    getCategoryGeneratedIndexList: () => SidebarItemCategoryWithGeneratedIndex[];
+    getCategoryGeneratedIndexNavigation: (categoryGeneratedIndexPermalink: string) => SidebarNavigation;
+    /**
+     * This function may return undefined. This is usually a user mistake, because
+     * it means this sidebar will never be displayed; however, we can still use
+     * `displayed_sidebar` to make it displayed. Pretty weird but valid use-case
+     */
+    getFirstLink: (sidebarId: string) => {
+        type: 'doc';
+        id: string;
+        label: string;
+    } | {
+        type: 'generated-index';
+        permalink: string;
+        label: string;
+    } | undefined;
+    checkLegacyVersionedSidebarNames: ({ versionMetadata, }: {
+        sidebarFilePath: string;
+        versionMetadata: VersionMetadata;
+    }) => void;
+    checkSidebarsDocIds: ({ allDocIds, sidebarFilePath, versionMetadata, }: {
+        allDocIds: string[];
+        sidebarFilePath: string;
+        versionMetadata: VersionMetadata;
+    }) => void;
+};
+export declare function createSidebarsUtils(sidebars: Sidebars): SidebarsUtils;
+export declare function toDocNavigationLink(doc: DocMetadataBase, options?: {
+    sidebarItemLabel?: string;
+}): PropNavigationLink;
+export declare function toNavigationLink(navigationItem: SidebarNavigationItem | undefined, docsById: {
+    [docId: string]: DocMetadataBase;
+}): PropNavigationLink | undefined;