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

package/lib/client/index.js

@@ -0,0 +1,83 @@
+/**
+ * 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 { useLocation } from '@docusaurus/router';
+import { useAllPluginInstancesData, usePluginData, } from '@docusaurus/useGlobalData';
+import { getActivePlugin, getLatestVersion, getActiveVersion, getActiveDocContext, getDocVersionSuggestions, } from './docsClientUtils';
+export { useDocById, findSidebarCategory, findFirstSidebarItemLink, isActiveSidebarItem, isVisibleSidebarItem, useVisibleSidebarItems, useSidebarBreadcrumbs, useDocsVersionCandidates, useLayoutDoc, useLayoutDocsSidebar, useDocRootMetadata, useCurrentSidebarCategory, useCurrentSidebarSiblings, filterDocCardListItems, } from './docsUtils';
+export { useDocsPreferredVersion } from './docsPreferredVersion';
+export { DocSidebarItemsExpandedStateProvider, useDocSidebarItemsExpandedState, } from './docSidebarItemsExpandedState';
+export { DocsVersionProvider, useDocsVersion } from './docsVersion';
+export { DocsSidebarProvider, useDocsSidebar } from './docsSidebar';
+export { DocProvider, useDoc } from './doc';
+export { useDocsPreferredVersionByPluginId, DocsPreferredVersionContextProvider, } from './docsPreferredVersion';
+export { useDocsContextualSearchTags, getDocsVersionSearchTag, } from './docsSearch';
+export { useBreadcrumbsStructuredData } from './structuredDataUtils';
+// Important to use a constant object to avoid React useEffect executions etc.
+// see https://github.com/facebook/docusaurus/issues/5089
+const StableEmptyObject = {};
+// 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
+export const useAllDocsData = () => useAllPluginInstancesData('docusaurus-plugin-content-docs') ?? StableEmptyObject;
+export const useDocsData = (pluginId) => {
+    try {
+        return usePluginData('docusaurus-plugin-content-docs', pluginId, {
+            failfast: true,
+        });
+    }
+    catch (error) {
+        throw new Error(`You are using a feature of the Docusaurus docs plugin, but this plugin does not seem to be enabled${pluginId === 'Default' ? '' : ` (pluginId=${pluginId}`}`, { cause: error });
+    }
+};
+// TODO this feature should be provided by docusaurus core
+export function useActivePlugin(options = {}) {
+    const data = useAllDocsData();
+    const { pathname } = useLocation();
+    return getActivePlugin(data, pathname, options);
+}
+export function useActivePluginAndVersion(options = {}) {
+    const activePlugin = useActivePlugin(options);
+    const { pathname } = useLocation();
+    if (!activePlugin) {
+        return undefined;
+    }
+    const activeVersion = getActiveVersion(activePlugin.pluginData, pathname);
+    return {
+        activePlugin,
+        activeVersion,
+    };
+}
+/** Versions are returned ordered (most recent first). */
+export function useVersions(pluginId) {
+    const data = useDocsData(pluginId);
+    return data.versions;
+}
+export function useLatestVersion(pluginId) {
+    const data = useDocsData(pluginId);
+    return getLatestVersion(data);
+}
+/**
+ * Returns `undefined` on doc-unrelated pages, because there's no version
+ * currently considered as active.
+ */
+export function useActiveVersion(pluginId) {
+    const data = useDocsData(pluginId);
+    const { pathname } = useLocation();
+    return getActiveVersion(data, pathname);
+}
+export function useActiveDocContext(pluginId) {
+    const data = useDocsData(pluginId);
+    const { pathname } = useLocation();
+    return getActiveDocContext(data, pathname);
+}
+/**
+ * Useful to say "hey, you are not on the latest docs version, please switch"
+ */
+export function useDocVersionSuggestions(pluginId) {
+    const data = useDocsData(pluginId);
+    const { pathname } = useLocation();
+    return getDocVersionSuggestions(data, pathname);
+}

package/lib/client/structuredDataUtils.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 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 { PropSidebarBreadcrumbsItem } from '@docusaurus/plugin-content-docs';
+import type { WithContext, BreadcrumbList } from 'schema-dts';
+export declare function useBreadcrumbsStructuredData({ breadcrumbs, }: {
+    breadcrumbs: PropSidebarBreadcrumbsItem[];
+}): WithContext<BreadcrumbList>;

package/lib/client/structuredDataUtils.js

@@ -0,0 +1,35 @@
+/**
+ * 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 useDocusaurusContext from '@docusaurus/useDocusaurusContext';
+import { applyTrailingSlash } from '@docusaurus/utils-common';
+function getAbsoluteUrl(permalink, params) {
+    const absoluteUrl = `${params.url}${permalink}`;
+    return applyTrailingSlash(absoluteUrl, {
+        trailingSlash: params.trailingSlash,
+        baseUrl: params.baseUrl,
+    });
+}
+function getBreadcrumbsStructuredData({ breadcrumbs, params, }) {
+    return {
+        '@context': 'https://schema.org',
+        '@type': 'BreadcrumbList',
+        itemListElement: breadcrumbs
+            // We filter breadcrumb items without links, they are not allowed
+            // See also https://github.com/facebook/docusaurus/issues/9319#issuecomment-2643560845
+            .filter((breadcrumb) => breadcrumb.href)
+            .map((breadcrumb, index) => ({
+            '@type': 'ListItem',
+            position: index + 1,
+            name: breadcrumb.label,
+            item: getAbsoluteUrl(breadcrumb.href, params),
+        })),
+    };
+}
+export function useBreadcrumbsStructuredData({ breadcrumbs, }) {
+    const { siteConfig } = useDocusaurusContext();
+    return getBreadcrumbsStructuredData({ breadcrumbs, params: siteConfig });
+}

package/lib/constants.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 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.
+ */
+/** The name of the version that's actively worked on (e.g. `website/docs`) */
+export declare const CURRENT_VERSION_NAME = "current";
+/** All doc versions are stored here by version names */
+export declare const VERSIONED_DOCS_DIR = "versioned_docs";
+/** All doc versioned sidebars are stored here by version names */
+export declare const VERSIONED_SIDEBARS_DIR = "versioned_sidebars";
+/** The version names. Should 1-1 map to the content of versioned docs dir. */
+export declare const VERSIONS_JSON_FILE = "versions.json";

package/lib/constants.js

@@ -0,0 +1,17 @@
+"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.VERSIONS_JSON_FILE = exports.VERSIONED_SIDEBARS_DIR = exports.VERSIONED_DOCS_DIR = exports.CURRENT_VERSION_NAME = void 0;
+/** The name of the version that's actively worked on (e.g. `website/docs`) */
+exports.CURRENT_VERSION_NAME = 'current';
+/** All doc versions are stored here by version names */
+exports.VERSIONED_DOCS_DIR = 'versioned_docs';
+/** All doc versioned sidebars are stored here by version names */
+exports.VERSIONED_SIDEBARS_DIR = 'versioned_sidebars';
+/** The version names. Should 1-1 map to the content of versioned docs dir. */
+exports.VERSIONS_JSON_FILE = 'versions.json';

package/lib/contentHelpers.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 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 { DocMetadata, LoadedContent } from '@docusaurus/plugin-content-docs';
+export declare function createContentHelpers(): {
+    updateContent: (content: LoadedContent) => void;
+    sourceToDoc: Map<string, DocMetadata>;
+    sourceToPermalink: Map<string, string>;
+};

package/lib/contentHelpers.js

@@ -0,0 +1,31 @@
+"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.createContentHelpers = createContentHelpers;
+function indexDocsBySource(content) {
+    const allDocs = content.loadedVersions.flatMap((v) => v.docs);
+    return new Map(allDocs.map((doc) => [doc.source, doc]));
+}
+// TODO this is bad, we should have a better way to do this (new lifecycle?)
+//  The source to doc/permalink is a mutable map passed to the mdx loader
+//  See https://github.com/facebook/docusaurus/pull/10457
+//  See https://github.com/facebook/docusaurus/pull/10185
+function createContentHelpers() {
+    const sourceToDoc = new Map();
+    const sourceToPermalink = new Map();
+    // Mutable map update :/
+    function updateContent(content) {
+        sourceToDoc.clear();
+        sourceToPermalink.clear();
+        indexDocsBySource(content).forEach((value, key) => {
+            sourceToDoc.set(key, value);
+            sourceToPermalink.set(key, value.permalink);
+        });
+    }
+    return { updateContent, sourceToDoc, sourceToPermalink };
+}

package/lib/docs.d.ts

@@ -0,0 +1,48 @@
+/**
+ * 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 { TagsFile } from '@docusaurus/utils';
+import type { MetadataOptions, PluginOptions, CategoryIndexMatcher, DocMetadataBase, VersionMetadata, LoadedVersion } from '@docusaurus/plugin-content-docs';
+import type { LoadContext } from '@docusaurus/types';
+import type { SidebarsUtils } from './sidebars/utils';
+import type { DocFile } from './types';
+export declare function readDocFile(versionMetadata: Pick<VersionMetadata, 'contentPath' | 'contentPathLocalized'>, source: string): Promise<DocFile>;
+export declare function readVersionDocs(versionMetadata: VersionMetadata, options: Pick<PluginOptions, 'include' | 'exclude' | 'showLastUpdateAuthor' | 'showLastUpdateTime'>): Promise<DocFile[]>;
+export type DocEnv = 'production' | 'development';
+export declare function processDocMetadata(args: {
+    docFile: DocFile;
+    versionMetadata: VersionMetadata;
+    context: LoadContext;
+    options: MetadataOptions;
+    env: DocEnv;
+    tagsFile: TagsFile | null;
+}): Promise<DocMetadataBase>;
+export declare function addDocNavigation({ docs, sidebarsUtils, }: {
+    docs: DocMetadataBase[];
+    sidebarsUtils: SidebarsUtils;
+}): LoadedVersion['docs'];
+/**
+ * The "main doc" is the "version entry point"
+ * We browse this doc by clicking on a version:
+ * - the "home" doc (at '/docs/')
+ * - the first doc of the first sidebar
+ * - a random doc (if no docs are in any sidebar... edge case)
+ */
+export declare function getMainDocId({ docs, sidebarsUtils, }: {
+    docs: DocMetadataBase[];
+    sidebarsUtils: SidebarsUtils;
+}): string;
+export declare const isCategoryIndex: CategoryIndexMatcher;
+/**
+ * `guides/sidebar/autogenerated.md` ->
+ *   `'autogenerated', '.md', ['sidebar', 'guides']`
+ */
+export declare function toCategoryIndexMatcherParam({ source, sourceDirName, }: Pick<DocMetadataBase, 'source' | 'sourceDirName'>): Parameters<CategoryIndexMatcher>[0];
+export declare function createDocsByIdIndex<Doc extends {
+    id: string;
+}>(docs: Doc[]): {
+    [docId: string]: Doc;
+};

package/lib/docs.js

@@ -0,0 +1,252 @@
+"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.isCategoryIndex = void 0;
+exports.readDocFile = readDocFile;
+exports.readVersionDocs = readVersionDocs;
+exports.processDocMetadata = processDocMetadata;
+exports.addDocNavigation = addDocNavigation;
+exports.getMainDocId = getMainDocId;
+exports.toCategoryIndexMatcherParam = toCategoryIndexMatcherParam;
+exports.createDocsByIdIndex = createDocsByIdIndex;
+const tslib_1 = require("tslib");
+const node_path_1 = tslib_1.__importDefault(require("node:path"));
+const lodash_1 = tslib_1.__importDefault(require("lodash"));
+const utils_1 = require("@docusaurus/utils");
+const glob_1 = require("@docusaurus/glob");
+const fs_1 = require("@docusaurus/fs");
+const frontMatter_1 = require("./frontMatter");
+const slug_1 = tslib_1.__importDefault(require("./slug"));
+const numberPrefix_1 = require("./numberPrefix");
+const utils_2 = require("./sidebars/utils");
+async function readDocFile(versionMetadata, source) {
+    const contentPath = await (0, utils_1.getFolderContainingFile)((0, utils_1.getContentPathList)(versionMetadata), source);
+    const filePath = node_path_1.default.join(contentPath, source);
+    const content = await fs_1.fs.readFile(filePath, 'utf-8');
+    return { source, content, contentPath, filePath };
+}
+async function readVersionDocs(versionMetadata, options) {
+    const sources = await (0, glob_1.glob)(options.include, {
+        cwd: versionMetadata.contentPath,
+        ignore: options.exclude,
+    });
+    return Promise.all(sources.map((source) => readDocFile(versionMetadata, source)));
+}
+async function doProcessDocMetadata({ docFile, versionMetadata, context, options, env, tagsFile, }) {
+    const { source, content, contentPath, filePath } = docFile;
+    const { siteDir, siteConfig: { markdown: { parseFrontMatter }, vcs, }, } = context;
+    const { frontMatter: unsafeFrontMatter, contentTitle, excerpt, } = await (0, utils_1.parseMarkdownFile)({
+        filePath,
+        fileContent: content,
+        parseFrontMatter,
+    });
+    const frontMatter = (0, frontMatter_1.validateDocFrontMatter)(unsafeFrontMatter);
+    const { custom_edit_url: customEditURL, 
+    // Strip number prefixes by default
+    // (01-MyFolder/01-MyDoc.md => MyFolder/MyDoc)
+    // but allow to disable this behavior with front matter
+    parse_number_prefixes: parseNumberPrefixes = true, last_update: lastUpdateFrontMatter, } = frontMatter;
+    const lastUpdate = await (0, utils_1.readLastUpdateData)(filePath, options, lastUpdateFrontMatter, vcs);
+    // E.g. api/plugins/myDoc -> myDoc; myDoc -> myDoc
+    const sourceFileNameWithoutExtension = node_path_1.default.basename(source, node_path_1.default.extname(source));
+    // E.g. api/plugins/myDoc -> api/plugins; myDoc -> .
+    const sourceDirName = node_path_1.default.dirname(source);
+    const { filename: unprefixedFileName, numberPrefix } = parseNumberPrefixes
+        ? options.numberPrefixParser(sourceFileNameWithoutExtension)
+        : { filename: sourceFileNameWithoutExtension, numberPrefix: undefined };
+    const baseID = frontMatter.id ?? unprefixedFileName;
+    if (baseID.includes('/')) {
+        throw new Error(`Document id "${baseID}" cannot include slash.`);
+    }
+    // For autogenerated sidebars, sidebar position can come from filename number
+    // prefix or front matter
+    const sidebarPosition = frontMatter.sidebar_position ?? numberPrefix;
+    // TODO legacy retrocompatibility
+    // I think it's bad to affect the front matter id with the dirname?
+    function computeDirNameIdPrefix() {
+        if (sourceDirName === '.') {
+            return undefined;
+        }
+        // Eventually remove the number prefixes from intermediate directories
+        return parseNumberPrefixes
+            ? (0, numberPrefix_1.stripPathNumberPrefixes)(sourceDirName, options.numberPrefixParser)
+            : sourceDirName;
+    }
+    const id = [computeDirNameIdPrefix(), baseID].filter(Boolean).join('/');
+    const docSlug = (0, slug_1.default)({
+        baseID,
+        source,
+        sourceDirName,
+        frontMatterSlug: frontMatter.slug,
+        stripDirNumberPrefixes: parseNumberPrefixes,
+        numberPrefixParser: options.numberPrefixParser,
+    });
+    // Note: the title is used by default for page title, sidebar label,
+    // pagination buttons... frontMatter.title should be used in priority over
+    // contentTitle (because it can contain markdown/JSX syntax)
+    const title = frontMatter.title ?? contentTitle ?? baseID;
+    const description = frontMatter.description ?? excerpt ?? '';
+    const permalink = (0, utils_1.normalizeUrl)([versionMetadata.path, docSlug]);
+    function getDocEditUrl() {
+        const relativeFilePath = node_path_1.default.relative(contentPath, filePath);
+        if (typeof options.editUrl === 'function') {
+            return options.editUrl({
+                version: versionMetadata.versionName,
+                versionDocsDirPath: (0, utils_1.posixPath)(node_path_1.default.relative(siteDir, versionMetadata.contentPath)),
+                docPath: (0, utils_1.posixPath)(relativeFilePath),
+                permalink,
+                locale: context.i18n.currentLocale,
+            });
+        }
+        else if (typeof options.editUrl === 'string') {
+            const isLocalized = typeof versionMetadata.contentPathLocalized !== 'undefined' &&
+                contentPath === versionMetadata.contentPathLocalized;
+            const baseVersionEditUrl = isLocalized && options.editLocalizedFiles
+                ? versionMetadata.editUrlLocalized
+                : versionMetadata.editUrl;
+            return (0, utils_1.getEditUrl)(relativeFilePath, baseVersionEditUrl);
+        }
+        return undefined;
+    }
+    const draft = (0, utils_1.isDraft)({ env, frontMatter });
+    const unlisted = (0, utils_1.isUnlisted)({ env, frontMatter });
+    const tags = (0, utils_1.normalizeTags)({
+        options,
+        source,
+        frontMatterTags: frontMatter.tags,
+        tagsBaseRoutePath: versionMetadata.tagsPath,
+        tagsFile,
+    });
+    // Assign all of object properties during instantiation (if possible) for
+    // NodeJS optimization.
+    // Adding properties to object after instantiation will cause hidden
+    // class transitions.
+    return {
+        id,
+        title,
+        description,
+        source: (0, utils_1.aliasedSitePath)(filePath, siteDir),
+        sourceDirName,
+        slug: docSlug,
+        permalink,
+        draft,
+        unlisted,
+        editUrl: customEditURL !== undefined ? customEditURL : getDocEditUrl(),
+        tags,
+        version: versionMetadata.versionName,
+        lastUpdatedBy: lastUpdate.lastUpdatedBy,
+        lastUpdatedAt: lastUpdate.lastUpdatedAt,
+        sidebarPosition,
+        frontMatter,
+    };
+}
+async function processDocMetadata(args) {
+    try {
+        return await doProcessDocMetadata(args);
+    }
+    catch (err) {
+        throw new Error(`Can't process doc metadata for doc at path path=${args.docFile.filePath} in version name=${args.versionMetadata.versionName}`, { cause: err });
+    }
+}
+function getUnlistedIds(docs) {
+    return new Set(docs.filter((doc) => doc.unlisted).map((doc) => doc.id));
+}
+function addDocNavigation({ docs, sidebarsUtils, }) {
+    const docsById = createDocsByIdIndex(docs);
+    const unlistedIds = getUnlistedIds(docs);
+    // Add sidebar/next/previous to the docs
+    function addNavData(doc) {
+        const navigation = sidebarsUtils.getDocNavigation({
+            docId: doc.id,
+            displayedSidebar: doc.frontMatter.displayed_sidebar,
+            unlistedIds,
+        });
+        const toNavigationLinkByDocId = (docId, type) => {
+            if (!docId) {
+                return undefined;
+            }
+            const navDoc = docsById[docId];
+            if (!navDoc) {
+                // This could only happen if user provided the ID through front matter
+                throw new Error(`Error when loading ${doc.id} in ${doc.sourceDirName}: the pagination_${type} front matter points to a non-existent ID ${docId}.`);
+            }
+            // Gracefully handle explicitly providing an unlisted doc ID in production
+            if (navDoc.unlisted) {
+                return undefined;
+            }
+            return (0, utils_2.toDocNavigationLink)(navDoc);
+        };
+        const previous = doc.frontMatter.pagination_prev !== undefined
+            ? toNavigationLinkByDocId(doc.frontMatter.pagination_prev, 'prev')
+            : (0, utils_2.toNavigationLink)(navigation.previous, docsById);
+        const next = doc.frontMatter.pagination_next !== undefined
+            ? toNavigationLinkByDocId(doc.frontMatter.pagination_next, 'next')
+            : (0, utils_2.toNavigationLink)(navigation.next, docsById);
+        return { ...doc, sidebar: navigation.sidebarName, previous, next };
+    }
+    const docsWithNavigation = docs.map(addNavData);
+    // Sort to ensure consistent output for tests
+    docsWithNavigation.sort((a, b) => a.id.localeCompare(b.id));
+    return docsWithNavigation;
+}
+/**
+ * The "main doc" is the "version entry point"
+ * We browse this doc by clicking on a version:
+ * - the "home" doc (at '/docs/')
+ * - the first doc of the first sidebar
+ * - a random doc (if no docs are in any sidebar... edge case)
+ */
+function getMainDocId({ docs, sidebarsUtils, }) {
+    function getMainDoc() {
+        const versionHomeDoc = docs.find((doc) => doc.slug === '/');
+        const firstDocIdOfFirstSidebar = sidebarsUtils.getFirstDocIdOfFirstSidebar();
+        if (versionHomeDoc) {
+            return versionHomeDoc;
+        }
+        else if (firstDocIdOfFirstSidebar) {
+            return docs.find((doc) => doc.id === firstDocIdOfFirstSidebar);
+        }
+        return docs[0];
+    }
+    return getMainDoc().id;
+}
+// By convention, Docusaurus considers some docs are "indexes":
+// - index.md
+// - readme.md
+// - <folder>/<folder>.md
+//
+// This function is the default implementation of this convention
+//
+// Those index docs produce a different behavior
+// - Slugs do not end with a weird "/index" suffix
+// - Auto-generated sidebar categories link to them as intro
+const isCategoryIndex = ({ fileName, directories, }) => {
+    const eligibleDocIndexNames = [
+        'index',
+        'readme',
+        directories[0]?.toLowerCase(),
+    ];
+    return eligibleDocIndexNames.includes(fileName.toLowerCase());
+};
+exports.isCategoryIndex = isCategoryIndex;
+/**
+ * `guides/sidebar/autogenerated.md` ->
+ *   `'autogenerated', '.md', ['sidebar', 'guides']`
+ */
+function toCategoryIndexMatcherParam({ source, sourceDirName, }) {
+    // source + sourceDirName are always posix-style
+    return {
+        fileName: node_path_1.default.posix.parse(source).name,
+        extension: node_path_1.default.posix.parse(source).ext,
+        directories: sourceDirName.split(node_path_1.default.posix.sep).reverse(),
+    };
+}
+// Docs are indexed by their id
+function createDocsByIdIndex(docs) {
+    return lodash_1.default.keyBy(docs, (d) => d.id);
+}

package/lib/frontMatter.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 { DocFrontMatter } from '@docusaurus/plugin-content-docs';
+export declare function validateDocFrontMatter(frontMatter: {
+    [key: string]: unknown;
+}): DocFrontMatter;

package/lib/frontMatter.js

@@ -0,0 +1,46 @@
+"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.
+ */
+/* eslint-disable camelcase */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateDocFrontMatter = validateDocFrontMatter;
+const utils_validation_1 = require("@docusaurus/utils-validation");
+// NOTE: we don't add any default value on purpose here
+// We don't want default values to magically appear in doc metadata and props
+// While the user did not provide those values explicitly
+// We use default values in code instead
+const DocFrontMatterSchema = utils_validation_1.JoiFrontMatter.object({
+    id: utils_validation_1.JoiFrontMatter.string(),
+    // See https://github.com/facebook/docusaurus/issues/4591#issuecomment-822372398
+    title: utils_validation_1.JoiFrontMatter.string().allow(''),
+    hide_title: utils_validation_1.JoiFrontMatter.boolean(),
+    hide_table_of_contents: utils_validation_1.JoiFrontMatter.boolean(),
+    keywords: utils_validation_1.JoiFrontMatter.array().items(utils_validation_1.JoiFrontMatter.string().required()),
+    image: utils_validation_1.URISchema,
+    // See https://github.com/facebook/docusaurus/issues/4591#issuecomment-822372398
+    description: utils_validation_1.JoiFrontMatter.string().allow(''),
+    slug: utils_validation_1.JoiFrontMatter.string(),
+    sidebar_key: utils_validation_1.JoiFrontMatter.string(),
+    sidebar_label: utils_validation_1.JoiFrontMatter.string(),
+    sidebar_position: utils_validation_1.JoiFrontMatter.number(),
+    sidebar_class_name: utils_validation_1.JoiFrontMatter.string(),
+    sidebar_custom_props: utils_validation_1.JoiFrontMatter.object().unknown(),
+    displayed_sidebar: utils_validation_1.JoiFrontMatter.string().allow(null),
+    tags: utils_validation_1.FrontMatterTagsSchema,
+    pagination_label: utils_validation_1.JoiFrontMatter.string(),
+    custom_edit_url: utils_validation_1.URISchema.allow('', null),
+    parse_number_prefixes: utils_validation_1.JoiFrontMatter.boolean(),
+    pagination_next: utils_validation_1.JoiFrontMatter.string().allow(null),
+    pagination_prev: utils_validation_1.JoiFrontMatter.string().allow(null),
+    ...utils_validation_1.FrontMatterTOCHeadingLevels,
+    last_update: utils_validation_1.FrontMatterLastUpdateSchema,
+})
+    .unknown()
+    .concat(utils_validation_1.ContentVisibilitySchema);
+function validateDocFrontMatter(frontMatter) {
+    return (0, utils_validation_1.validateFrontMatter)(frontMatter, DocFrontMatterSchema);
+}

package/lib/globalData.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 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 { FullVersion } from './types';
+import type { GlobalVersion } from '@docusaurus/plugin-content-docs/client';
+export declare function toGlobalDataVersion(version: FullVersion): GlobalVersion;

package/lib/globalData.js

@@ -0,0 +1,59 @@
+"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.toGlobalDataVersion = toGlobalDataVersion;
+const tslib_1 = require("tslib");
+const lodash_1 = tslib_1.__importDefault(require("lodash"));
+const docs_1 = require("./docs");
+function toGlobalDataDoc(doc) {
+    return {
+        id: doc.id,
+        path: doc.permalink,
+        // optimize global data size: do not add unlisted: false/undefined
+        ...(doc.unlisted && { unlisted: doc.unlisted }),
+        // TODO optimize size? remove attribute when no sidebar (breaking change?)
+        sidebar: doc.sidebar,
+    };
+}
+function toGlobalDataGeneratedIndex(doc) {
+    return {
+        id: doc.slug,
+        path: doc.permalink,
+        sidebar: doc.sidebar,
+    };
+}
+function toGlobalSidebars(sidebars, version) {
+    return lodash_1.default.mapValues(sidebars, (sidebar, sidebarId) => {
+        const firstLink = version.sidebarsUtils.getFirstLink(sidebarId);
+        if (!firstLink) {
+            return {};
+        }
+        return {
+            link: {
+                path: firstLink.type === 'generated-index'
+                    ? firstLink.permalink
+                    : version.docs.find((doc) => doc.id === firstLink.id).permalink,
+                label: firstLink.label,
+            },
+        };
+    });
+}
+function toGlobalDataVersion(version) {
+    return {
+        name: version.versionName,
+        label: version.label,
+        isLast: version.isLast,
+        path: version.path,
+        mainDocId: (0, docs_1.getMainDocId)(version),
+        docs: version.docs
+            .map(toGlobalDataDoc)
+            .concat(version.categoryGeneratedIndices.map(toGlobalDataGeneratedIndex)),
+        draftIds: version.drafts.map((doc) => doc.id),
+        sidebars: toGlobalSidebars(version.sidebars, version),
+    };
+}

package/lib/index.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 { PluginOptions, LoadedContent } from '@docusaurus/plugin-content-docs';
+import type { LoadContext, Plugin } from '@docusaurus/types';
+export default function pluginContentDocs(context: LoadContext, options: PluginOptions): Promise<Plugin<LoadedContent>>;
+export { validateOptions } from './options';