@docusaurus/plugin-content-docs 3.3.2 → 3.5.0

package/lib/client/docsUtils.js

@@ -0,0 +1,273 @@
+/**
+ * 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 { useMemo } from 'react';
+import { matchPath, useLocation } from '@docusaurus/router';
+import renderRoutes from '@docusaurus/renderRoutes';
+import { useActivePlugin, useActiveDocContext, useLatestVersion, } from '@docusaurus/plugin-content-docs/client';
+import { isSamePath } from '@docusaurus/theme-common/internal';
+import { uniq } from '@docusaurus/theme-common';
+import { useDocsPreferredVersion } from './docsPreferredVersion';
+import { useDocsVersion } from './docsVersion';
+import { useDocsSidebar } from './docsSidebar';
+export function useDocById(id) {
+    const version = useDocsVersion();
+    if (!id) {
+        return undefined;
+    }
+    const doc = version.docs[id];
+    if (!doc) {
+        throw new Error(`no version doc found by id=${id}`);
+    }
+    return doc;
+}
+/**
+ * Pure function, similar to `Array#find`, but works on the sidebar tree.
+ */
+export function findSidebarCategory(sidebar, predicate) {
+    for (const item of sidebar) {
+        if (item.type === 'category') {
+            if (predicate(item)) {
+                return item;
+            }
+            const subItem = findSidebarCategory(item.items, predicate);
+            if (subItem) {
+                return subItem;
+            }
+        }
+    }
+    return undefined;
+}
+/**
+ * Best effort to assign a link to a sidebar category. If the category doesn't
+ * have a link itself, we link to the first sub item with a link.
+ */
+export function findFirstSidebarItemCategoryLink(item) {
+    if (item.href && !item.linkUnlisted) {
+        return item.href;
+    }
+    for (const subItem of item.items) {
+        const link = findFirstSidebarItemLink(subItem);
+        if (link) {
+            return link;
+        }
+    }
+    return undefined;
+}
+/**
+ * Best effort to assign a link to a sidebar item.
+ */
+export function findFirstSidebarItemLink(item) {
+    if (item.type === 'link' && !item.unlisted) {
+        return item.href;
+    }
+    if (item.type === 'category') {
+        return findFirstSidebarItemCategoryLink(item);
+    }
+    // Other items types, like "html"
+    return undefined;
+}
+/**
+ * Gets the category associated with the current location. Should only be used
+ * on category index pages.
+ */
+export function useCurrentSidebarCategory() {
+    const { pathname } = useLocation();
+    const sidebar = useDocsSidebar();
+    if (!sidebar) {
+        throw new Error('Unexpected: cant find current sidebar in context');
+    }
+    const categoryBreadcrumbs = getSidebarBreadcrumbs({
+        sidebarItems: sidebar.items,
+        pathname,
+        onlyCategories: true,
+    });
+    const deepestCategory = categoryBreadcrumbs.slice(-1)[0];
+    if (!deepestCategory) {
+        throw new Error(`${pathname} is not associated with a category. useCurrentSidebarCategory() should only be used on category index pages.`);
+    }
+    return deepestCategory;
+}
+const isActive = (testedPath, activePath) => typeof testedPath !== 'undefined' && isSamePath(testedPath, activePath);
+const containsActiveSidebarItem = (items, activePath) => items.some((subItem) => isActiveSidebarItem(subItem, activePath));
+/**
+ * Checks if a sidebar item should be active, based on the active path.
+ */
+export function isActiveSidebarItem(item, activePath) {
+    if (item.type === 'link') {
+        return isActive(item.href, activePath);
+    }
+    if (item.type === 'category') {
+        return (isActive(item.href, activePath) ||
+            containsActiveSidebarItem(item.items, activePath));
+    }
+    return false;
+}
+export function isVisibleSidebarItem(item, activePath) {
+    switch (item.type) {
+        case 'category':
+            return (isActiveSidebarItem(item, activePath) ||
+                item.items.some((subItem) => isVisibleSidebarItem(subItem, activePath)));
+        case 'link':
+            // An unlisted item remains visible if it is active
+            return !item.unlisted || isActiveSidebarItem(item, activePath);
+        default:
+            return true;
+    }
+}
+export function useVisibleSidebarItems(items, activePath) {
+    return useMemo(() => items.filter((item) => isVisibleSidebarItem(item, activePath)), [items, activePath]);
+}
+/**
+ * Get the sidebar the breadcrumbs for a given pathname
+ * Ordered from top to bottom
+ */
+function getSidebarBreadcrumbs({ sidebarItems, pathname, onlyCategories = false, }) {
+    const breadcrumbs = [];
+    function extract(items) {
+        for (const item of items) {
+            if ((item.type === 'category' &&
+                (isSamePath(item.href, pathname) || extract(item.items))) ||
+                (item.type === 'link' && isSamePath(item.href, pathname))) {
+                const filtered = onlyCategories && item.type !== 'category';
+                if (!filtered) {
+                    breadcrumbs.unshift(item);
+                }
+                return true;
+            }
+        }
+        return false;
+    }
+    extract(sidebarItems);
+    return breadcrumbs;
+}
+/**
+ * Gets the breadcrumbs of the current doc page, based on its sidebar location.
+ * Returns `null` if there's no sidebar or breadcrumbs are disabled.
+ */
+export function useSidebarBreadcrumbs() {
+    const sidebar = useDocsSidebar();
+    const { pathname } = useLocation();
+    const breadcrumbsOption = useActivePlugin()?.pluginData.breadcrumbs;
+    if (breadcrumbsOption === false || !sidebar) {
+        return null;
+    }
+    return getSidebarBreadcrumbs({ sidebarItems: sidebar.items, pathname });
+}
+/**
+ * "Version candidates" are mostly useful for the layout components, which must
+ * be able to work on all pages. For example, if a user has `{ type: "doc",
+ * docId: "intro" }` as a navbar item, which version does that refer to? We
+ * believe that it could refer to at most three version candidates:
+ *
+ * 1. The **active version**, the one that the user is currently browsing. See
+ * {@link useActiveDocContext}.
+ * 2. The **preferred version**, the one that the user last visited. See
+ * {@link useDocsPreferredVersion}.
+ * 3. The **latest version**, the "default". See {@link useLatestVersion}.
+ *
+ * @param docsPluginId The plugin ID to get versions from.
+ * @returns An array of 1~3 versions with priorities defined above, guaranteed
+ * to be unique and non-sparse. Will be memoized, hence stable for deps array.
+ */
+export function useDocsVersionCandidates(docsPluginId) {
+    const { activeVersion } = useActiveDocContext(docsPluginId);
+    const { preferredVersion } = useDocsPreferredVersion(docsPluginId);
+    const latestVersion = useLatestVersion(docsPluginId);
+    return useMemo(() => uniq([activeVersion, preferredVersion, latestVersion].filter(Boolean)), [activeVersion, preferredVersion, latestVersion]);
+}
+/**
+ * The layout components, like navbar items, must be able to work on all pages,
+ * even on non-doc ones where there's no version context, so a sidebar ID could
+ * be ambiguous. This hook would always return a sidebar to be linked to. See
+ * also {@link useDocsVersionCandidates} for how this selection is done.
+ *
+ * @throws This hook throws if a sidebar with said ID is not found.
+ */
+export function useLayoutDocsSidebar(sidebarId, docsPluginId) {
+    const versions = useDocsVersionCandidates(docsPluginId);
+    return useMemo(() => {
+        const allSidebars = versions.flatMap((version) => version.sidebars ? Object.entries(version.sidebars) : []);
+        const sidebarEntry = allSidebars.find((sidebar) => sidebar[0] === sidebarId);
+        if (!sidebarEntry) {
+            throw new Error(`Can't find any sidebar with id "${sidebarId}" in version${versions.length > 1 ? 's' : ''} ${versions.map((version) => version.name).join(', ')}".
+Available sidebar ids are:
+- ${allSidebars.map((entry) => entry[0]).join('\n- ')}`);
+        }
+        return sidebarEntry[1];
+    }, [sidebarId, versions]);
+}
+/**
+ * The layout components, like navbar items, must be able to work on all pages,
+ * even on non-doc ones where there's no version context, so a doc ID could be
+ * ambiguous. This hook would always return a doc to be linked to. See also
+ * {@link useDocsVersionCandidates} for how this selection is done.
+ *
+ * @throws This hook throws if a doc with said ID is not found.
+ */
+export function useLayoutDoc(docId, docsPluginId) {
+    const versions = useDocsVersionCandidates(docsPluginId);
+    return useMemo(() => {
+        const allDocs = versions.flatMap((version) => version.docs);
+        const doc = allDocs.find((versionDoc) => versionDoc.id === docId);
+        if (!doc) {
+            const isDraft = versions
+                .flatMap((version) => version.draftIds)
+                .includes(docId);
+            // Drafts should be silently filtered instead of throwing
+            if (isDraft) {
+                return null;
+            }
+            throw new Error(`Couldn't find any doc with id "${docId}" in version${versions.length > 1 ? 's' : ''} "${versions.map((version) => version.name).join(', ')}".
+Available doc ids are:
+- ${uniq(allDocs.map((versionDoc) => versionDoc.id)).join('\n- ')}`);
+        }
+        return doc;
+    }, [docId, versions]);
+}
+// TODO later read version/route directly from context
+/**
+ * The docs plugin creates nested routes, with the top-level route providing the
+ * version metadata, and the subroutes creating individual doc pages. This hook
+ * will match the current location against all known sub-routes.
+ *
+ * @param props The props received by `@theme/DocRoot`
+ * @returns The data of the relevant document at the current location, or `null`
+ * if no document associated with the current location can be found.
+ */
+export function useDocRootMetadata({ route }) {
+    const location = useLocation();
+    const versionMetadata = useDocsVersion();
+    const docRoutes = route.routes;
+    const currentDocRoute = docRoutes.find((docRoute) => matchPath(location.pathname, docRoute));
+    if (!currentDocRoute) {
+        return null;
+    }
+    // For now, the sidebarName is added as route config: not ideal!
+    const sidebarName = currentDocRoute.sidebar;
+    const sidebarItems = sidebarName
+        ? versionMetadata.docsSidebars[sidebarName]
+        : undefined;
+    const docElement = renderRoutes(docRoutes);
+    return {
+        docElement,
+        sidebarName,
+        sidebarItems,
+    };
+}
+/**
+ * Filter items we don't want to display on the doc card list view
+ * @param items
+ */
+export function filterDocCardListItems(items) {
+    return items.filter((item) => {
+        const canHaveLink = item.type === 'category' || item.type === 'link';
+        if (canHaveLink) {
+            return !!findFirstSidebarItemLink(item);
+        }
+        return true;
+    });
+}

package/lib/client/docsVersion.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 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 ReactNode } from 'react';
+import type { PropVersionMetadata } from '@docusaurus/plugin-content-docs';
+/**
+ * Provide the current version's metadata to your children.
+ */
+export declare function DocsVersionProvider({ children, version, }: {
+    children: ReactNode;
+    version: PropVersionMetadata | null;
+}): JSX.Element;
+/**
+ * Gets the version metadata of the current doc page.
+ */
+export declare function useDocsVersion(): PropVersionMetadata;

package/lib/client/docsVersion.js

@@ -0,0 +1,25 @@
+/**
+ * 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 React, { useContext } from 'react';
+import { ReactContextError } from '@docusaurus/theme-common/internal';
+const Context = React.createContext(null);
+/**
+ * Provide the current version's metadata to your children.
+ */
+export function DocsVersionProvider({ children, version, }) {
+    return <Context.Provider value={version}>{children}</Context.Provider>;
+}
+/**
+ * Gets the version metadata of the current doc page.
+ */
+export function useDocsVersion() {
+    const version = useContext(Context);
+    if (version === null) {
+        throw new ReactContextError('DocsVersionProvider');
+    }
+    return version;
+}

package/lib/client/index.d.ts

@@ -5,6 +5,14 @@
  * LICENSE file in the root directory of this source tree.
  */
 import type { UseDataOptions } from '@docusaurus/types';
+export { useDocById, findSidebarCategory, findFirstSidebarItemLink, isActiveSidebarItem, isVisibleSidebarItem, useVisibleSidebarItems, useSidebarBreadcrumbs, useDocsVersionCandidates, useLayoutDoc, useLayoutDocsSidebar, useDocRootMetadata, useCurrentSidebarCategory, 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, type DocContextValue } from './doc';
+export { useDocsPreferredVersionByPluginId, DocsPreferredVersionContextProvider, } from './docsPreferredVersion';
+export { useDocsContextualSearchTags, getDocsVersionSearchTag, } from './docsSearch';
 export type ActivePlugin = {
     pluginId: string;
     pluginData: GlobalPluginData;

package/lib/client/index.js

@@ -7,6 +7,14 @@
 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, 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';
 // Important to use a constant object to avoid React useEffect executions etc.
 // see https://github.com/facebook/docusaurus/issues/5089
 const StableEmptyObject = {};

package/lib/docs.d.ts

@@ -4,7 +4,7 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-/// <reference path="../src/plugin-content-docs.d.ts" />
+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';
@@ -18,6 +18,7 @@ export declare function processDocMetadata(args: {
     context: LoadContext;
     options: MetadataOptions;
     env: DocEnv;
+    tagsFile: TagsFile | null;
 }): Promise<DocMetadataBase>;
 export declare function addDocNavigation({ docs, sidebarsUtils, }: {
     docs: DocMetadataBase[];

package/lib/docs.js

@@ -6,7 +6,14 @@
  * LICENSE file in the root directory of this source tree.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createDocsByIdIndex = exports.toCategoryIndexMatcherParam = exports.isCategoryIndex = exports.getMainDocId = exports.addDocNavigation = exports.processDocMetadata = exports.readVersionDocs = exports.readDocFile = void 0;
+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 path_1 = tslib_1.__importDefault(require("path"));
 const fs_extra_1 = tslib_1.__importDefault(require("fs-extra"));
@@ -22,7 +29,6 @@ async function readDocFile(versionMetadata, source) {
     const content = await fs_extra_1.default.readFile(filePath, 'utf-8');
     return { source, content, contentPath, filePath };
 }
-exports.readDocFile = readDocFile;
 async function readVersionDocs(versionMetadata, options) {
     const sources = await (0, utils_1.Globby)(options.include, {
         cwd: versionMetadata.contentPath,
@@ -30,8 +36,7 @@ async function readVersionDocs(versionMetadata, options) {
     });
     return Promise.all(sources.map((source) => readDocFile(versionMetadata, source)));
 }
-exports.readVersionDocs = readVersionDocs;
-async function doProcessDocMetadata({ docFile, versionMetadata, context, options, env, }) {
+async function doProcessDocMetadata({ docFile, versionMetadata, context, options, env, tagsFile, }) {
     const { source, content, contentPath, filePath } = docFile;
     const { siteDir, siteConfig: { markdown: { parseFrontMatter }, }, } = context;
     const { frontMatter: unsafeFrontMatter, contentTitle, excerpt, } = await (0, utils_1.parseMarkdownFile)({
@@ -108,6 +113,13 @@ async function doProcessDocMetadata({ docFile, versionMetadata, context, options
     }
     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
@@ -123,7 +135,7 @@ async function doProcessDocMetadata({ docFile, versionMetadata, context, options
         draft,
         unlisted,
         editUrl: customEditURL !== undefined ? customEditURL : getDocEditUrl(),
-        tags: (0, utils_1.normalizeFrontMatterTags)(versionMetadata.tagsPath, frontMatter.tags),
+        tags,
         version: versionMetadata.versionName,
         lastUpdatedBy: lastUpdate.lastUpdatedBy,
         lastUpdatedAt: lastUpdate.lastUpdatedAt,
@@ -139,7 +151,6 @@ async function processDocMetadata(args) {
         throw new Error(`Can't process doc metadata for doc at path path=${args.docFile.filePath} in version name=${args.versionMetadata.versionName}`, { cause: err });
     }
 }
-exports.processDocMetadata = processDocMetadata;
 function getUnlistedIds(docs) {
     return new Set(docs.filter((doc) => doc.unlisted).map((doc) => doc.id));
 }
@@ -181,7 +192,6 @@ function addDocNavigation({ docs, sidebarsUtils, }) {
     docsWithNavigation.sort((a, b) => a.id.localeCompare(b.id));
     return docsWithNavigation;
 }
-exports.addDocNavigation = addDocNavigation;
 /**
  * The "main doc" is the "version entry point"
  * We browse this doc by clicking on a version:
@@ -203,7 +213,6 @@ function getMainDocId({ docs, sidebarsUtils, }) {
     }
     return getMainDoc().id;
 }
-exports.getMainDocId = getMainDocId;
 // By convention, Docusaurus considers some docs are "indexes":
 // - index.md
 // - readme.md
@@ -235,9 +244,7 @@ function toCategoryIndexMatcherParam({ source, sourceDirName, }) {
         directories: sourceDirName.split(path_1.default.posix.sep).reverse(),
     };
 }
-exports.toCategoryIndexMatcherParam = toCategoryIndexMatcherParam;
 // Docs are indexed by their id
 function createDocsByIdIndex(docs) {
     return lodash_1.default.keyBy(docs, (d) => d.id);
 }
-exports.createDocsByIdIndex = createDocsByIdIndex;

package/lib/frontMatter.d.ts

@@ -1,4 +1,3 @@
-/// <reference path="../src/plugin-content-docs.d.ts" />
 import type { DocFrontMatter } from '@docusaurus/plugin-content-docs';
 export declare const DocFrontMatterSchema: import("joi").ObjectSchema<DocFrontMatter>;
 export declare function validateDocFrontMatter(frontMatter: {

package/lib/frontMatter.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.validateDocFrontMatter = exports.DocFrontMatterSchema = void 0;
+exports.DocFrontMatterSchema = void 0;
+exports.validateDocFrontMatter = validateDocFrontMatter;
 /**
  * Copyright (c) Facebook, Inc. and its affiliates.
  *
@@ -42,4 +43,3 @@ exports.DocFrontMatterSchema = utils_validation_1.JoiFrontMatter.object({
 function validateDocFrontMatter(frontMatter) {
     return (0, utils_validation_1.validateFrontMatter)(frontMatter, exports.DocFrontMatterSchema);
 }
-exports.validateDocFrontMatter = validateDocFrontMatter;

package/lib/globalData.js

@@ -6,7 +6,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.toGlobalDataVersion = void 0;
+exports.toGlobalDataVersion = toGlobalDataVersion;
 const tslib_1 = require("tslib");
 const lodash_1 = tslib_1.__importDefault(require("lodash"));
 const docs_1 = require("./docs");
@@ -57,4 +57,3 @@ function toGlobalDataVersion(version) {
         sidebars: toGlobalSidebars(version.sidebars, version),
     };
 }
-exports.toGlobalDataVersion = toGlobalDataVersion;

package/lib/index.d.ts

@@ -4,7 +4,6 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-/// <reference path="../src/plugin-content-docs.d.ts" />
 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>>;