@docusaurus/plugin-content-docs 3.7.0 → 3.8.0

package/lib/cli.js

@@ -76,6 +76,23 @@ async function cliDocsVersionCommand(version, { id: pluginId, path: docsPath, si
                 versionName: version,
             });
         await fs_extra_1.default.copy(docsDir, newVersionDir);
+        // Copy version JSON translation file for this locale
+        // i18n/<l>/docusaurus-plugin-content-docs/current.json => version-v1.json
+        // See https://docusaurus.io/docs/next/api/plugins/@docusaurus/plugin-content-docs#translation-files-location
+        if (locale !== i18n.defaultLocale) {
+            const dir = (0, files_1.getPluginDirPathLocalized)({
+                localizationDir,
+                pluginId,
+            });
+            const sourceFile = path_1.default.join(dir, 'current.json');
+            const dest = path_1.default.join(dir, `version-${version}.json`);
+            if (await fs_extra_1.default.pathExists(sourceFile)) {
+                await fs_extra_1.default.copy(sourceFile, dest);
+            }
+            else {
+                logger_1.default.warn `${pluginIdLogPrefix}: i18n translation file does not exist in path=${sourceFile}. Skipping.`;
+            }
+        }
     }));
     await createVersionedSidebarFile({
         siteDir,

package/lib/client/docsUtils.d.ts

@@ -34,6 +34,11 @@ export declare function findFirstSidebarItemLink(item: PropSidebarItem): string
  * on category index pages.
  */
 export declare function useCurrentSidebarCategory(): PropSidebarItemCategory;
+/**
+ * Gets the category associated with the current location. Should only be used
+ * on category index pages.
+ */
+export declare function useCurrentSidebarSiblings(): PropSidebarItem[];
 /**
  * Checks if a sidebar item should be active, based on the active path.
  */

package/lib/client/docsUtils.js

@@ -91,6 +91,24 @@ export function useCurrentSidebarCategory() {
     }
     return deepestCategory;
 }
+/**
+ * Gets the category associated with the current location. Should only be used
+ * on category index pages.
+ */
+export function useCurrentSidebarSiblings() {
+    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];
+    return deepestCategory?.items ?? sidebar.items;
+}
 const isActive = (testedPath, activePath) => typeof testedPath !== 'undefined' && isSamePath(testedPath, activePath);
 const containsActiveSidebarItem = (items, activePath) => items.some((subItem) => isActiveSidebarItem(subItem, activePath));
 /**

package/lib/client/index.d.ts

@@ -5,7 +5,7 @@
  * 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 { 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';
@@ -13,6 +13,7 @@ export { DocsSidebarProvider, useDocsSidebar } from './docsSidebar';
 export { DocProvider, useDoc, type DocContextValue } from './doc';
 export { useDocsPreferredVersionByPluginId, DocsPreferredVersionContextProvider, } from './docsPreferredVersion';
 export { useDocsContextualSearchTags, getDocsVersionSearchTag, } from './docsSearch';
+export { useBreadcrumbsStructuredData } from './structuredDataUtils';
 export type ActivePlugin = {
     pluginId: string;
     pluginData: GlobalPluginData;

package/lib/client/index.js

@@ -7,7 +7,7 @@
 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 { 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';
@@ -15,6 +15,7 @@ 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 = {};

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,24 @@
+/**
+ * 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';
+export function useBreadcrumbsStructuredData({ breadcrumbs, }) {
+    const { siteConfig } = useDocusaurusContext();
+    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: `${siteConfig.url}${breadcrumb.href}`,
+        })),
+    };
+}

package/lib/index.js

@@ -10,6 +10,7 @@ exports.validateOptions = void 0;
 exports.default = pluginContentDocs;
 const tslib_1 = require("tslib");
 const path_1 = tslib_1.__importDefault(require("path"));
+const fs_extra_1 = tslib_1.__importDefault(require("fs-extra"));
 const lodash_1 = tslib_1.__importDefault(require("lodash"));
 const logger_1 = tslib_1.__importDefault(require("@docusaurus/logger"));
 const utils_1 = require("@docusaurus/utils");
@@ -26,6 +27,21 @@ const translations_1 = require("./translations");
 const routes_1 = require("./routes");
 const utils_2 = require("./sidebars/utils");
 const contentHelpers_1 = require("./contentHelpers");
+// MDX loader is not 100% deterministic, leading to cache invalidation issue
+// This permits to invalidate the MDX loader cache entries when content changes
+// Problem documented here: https://github.com/facebook/docusaurus/pull/10934
+// TODO this is not a perfect solution, find better?
+async function createMdxLoaderDependencyFile({ dataDir, options, versionsMetadata, }) {
+    const filePath = path_1.default.join(dataDir, '__mdx-loader-dependency.json');
+    // the cache is invalidated whenever this file content changes
+    const fileContent = {
+        options,
+        versionsMetadata,
+    };
+    await fs_extra_1.default.ensureDir(dataDir);
+    await fs_extra_1.default.writeFile(filePath, JSON.stringify(fileContent));
+    return filePath;
+}
 async function pluginContentDocs(context, options) {
     const { siteDir, generatedFilesDir, baseUrl, siteConfig } = context;
     // Mutate options to resolve sidebar path according to siteDir
@@ -50,6 +66,13 @@ async function pluginContentDocs(context, options) {
         return (0, mdx_loader_1.createMDXLoaderRule)({
             include: contentDirs,
             options: {
+                dependencies: [
+                    await createMdxLoaderDependencyFile({
+                        dataDir,
+                        options,
+                        versionsMetadata,
+                    }),
+                ].filter((d) => typeof d === 'string'),
                 useCrossCompilerCache: siteConfig.future.experimental_faster.mdxCrossCompilerCache,
                 admonitions: options.admonitions,
                 remarkPlugins,

package/lib/versions/files.d.ts

@@ -15,6 +15,10 @@ export declare function getDocsDirPathLocalized({ localizationDir, pluginId, ver
     pluginId: string;
     versionName: string;
 }): string;
+export declare function getPluginDirPathLocalized({ localizationDir, pluginId, }: {
+    localizationDir: string;
+    pluginId: string;
+}): string;
 /** `community` => `[siteDir]/community_versions.json` */
 export declare function getVersionsFilePath(siteDir: string, pluginId: string): string;
 /**

package/lib/versions/files.js

@@ -9,6 +9,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.getVersionDocsDirPath = getVersionDocsDirPath;
 exports.getVersionSidebarsPath = getVersionSidebarsPath;
 exports.getDocsDirPathLocalized = getDocsDirPathLocalized;
+exports.getPluginDirPathLocalized = getPluginDirPathLocalized;
 exports.getVersionsFilePath = getVersionsFilePath;
 exports.readVersionsFile = readVersionsFile;
 exports.readVersionNames = readVersionNames;
@@ -45,6 +46,14 @@ function getDocsDirPathLocalized({ localizationDir, pluginId, versionName, }) {
         ],
     });
 }
+function getPluginDirPathLocalized({ localizationDir, pluginId, }) {
+    return (0, utils_1.getPluginI18nPath)({
+        localizationDir,
+        pluginName: 'docusaurus-plugin-content-docs',
+        pluginId,
+        subPaths: [],
+    });
+}
 /** `community` => `[siteDir]/community_versions.json` */
 function getVersionsFilePath(siteDir, pluginId) {
     return path_1.default.join(siteDir, addPluginIdPrefix(constants_1.VERSIONS_JSON_FILE, pluginId));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/plugin-content-docs",
-  "version": "3.7.0",
+  "version": "3.8.0",
   "description": "Docs plugin for Docusaurus.",
   "main": "lib/index.js",
   "sideEffects": false,
@@ -35,20 +35,21 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/core": "3.7.0",
-    "@docusaurus/logger": "3.7.0",
-    "@docusaurus/mdx-loader": "3.7.0",
-    "@docusaurus/module-type-aliases": "3.7.0",
-    "@docusaurus/theme-common": "3.7.0",
-    "@docusaurus/types": "3.7.0",
-    "@docusaurus/utils": "3.7.0",
-    "@docusaurus/utils-common": "3.7.0",
-    "@docusaurus/utils-validation": "3.7.0",
+    "@docusaurus/core": "3.8.0",
+    "@docusaurus/logger": "3.8.0",
+    "@docusaurus/mdx-loader": "3.8.0",
+    "@docusaurus/module-type-aliases": "3.8.0",
+    "@docusaurus/theme-common": "3.8.0",
+    "@docusaurus/types": "3.8.0",
+    "@docusaurus/utils": "3.8.0",
+    "@docusaurus/utils-common": "3.8.0",
+    "@docusaurus/utils-validation": "3.8.0",
     "@types/react-router-config": "^5.0.7",
     "combine-promises": "^1.1.0",
     "fs-extra": "^11.1.1",
     "js-yaml": "^4.1.0",
     "lodash": "^4.17.21",
+    "schema-dts": "^1.1.2",
     "tslib": "^2.6.0",
     "utility-types": "^3.10.0",
     "webpack": "^5.88.1"
@@ -57,8 +58,7 @@
     "@types/js-yaml": "^4.0.5",
     "@types/picomatch": "^2.3.0",
     "commander": "^5.1.0",
-    "picomatch": "^2.3.1",
-    "shelljs": "^0.8.5"
+    "picomatch": "^2.3.1"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",
@@ -67,5 +67,5 @@
   "engines": {
     "node": ">=18.0"
   },
-  "gitHead": "dd59750c16fe6908a26f18806a54d4c3dbe6db43"
+  "gitHead": "948d63c42fad0ba24b7b531a9deb6167e64dc845"
 }

package/src/cli.ts

@@ -14,6 +14,7 @@ import {
   getVersionDocsDirPath,
   getVersionSidebarsPath,
   getDocsDirPathLocalized,
+  getPluginDirPathLocalized,
   readVersionsFile,
 } from './versions/files';
 import {validateVersionName} from './versions/validation';
@@ -123,6 +124,23 @@ async function cliDocsVersionCommand(
               versionName: version,
             });
       await fs.copy(docsDir, newVersionDir);
+
+      // Copy version JSON translation file for this locale
+      // i18n/<l>/docusaurus-plugin-content-docs/current.json => version-v1.json
+      // See https://docusaurus.io/docs/next/api/plugins/@docusaurus/plugin-content-docs#translation-files-location
+      if (locale !== i18n.defaultLocale) {
+        const dir = getPluginDirPathLocalized({
+          localizationDir,
+          pluginId,
+        });
+        const sourceFile = path.join(dir, 'current.json');
+        const dest = path.join(dir, `version-${version}.json`);
+        if (await fs.pathExists(sourceFile)) {
+          await fs.copy(sourceFile, dest);
+        } else {
+          logger.warn`${pluginIdLogPrefix}: i18n translation file does not exist in path=${sourceFile}. Skipping.`;
+        }
+      }
     }),
   );
 

package/src/client/docsUtils.tsx

@@ -132,6 +132,25 @@ export function useCurrentSidebarCategory(): PropSidebarItemCategory {
   return deepestCategory;
 }
 
+/**
+ * Gets the category associated with the current location. Should only be used
+ * on category index pages.
+ */
+export function useCurrentSidebarSiblings(): PropSidebarItem[] {
+  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];
+  return deepestCategory?.items ?? sidebar.items;
+}
+
 const isActive = (testedPath: string | undefined, activePath: string) =>
   typeof testedPath !== 'undefined' && isSamePath(testedPath, activePath);
 const containsActiveSidebarItem = (

package/src/client/index.ts

@@ -33,6 +33,7 @@ export {
   useLayoutDocsSidebar,
   useDocRootMetadata,
   useCurrentSidebarCategory,
+  useCurrentSidebarSiblings,
   filterDocCardListItems,
 } from './docsUtils';
 
@@ -59,6 +60,8 @@ export {
   getDocsVersionSearchTag,
 } from './docsSearch';
 
+export {useBreadcrumbsStructuredData} from './structuredDataUtils';
+
 export type ActivePlugin = {
   pluginId: string;
   pluginData: GlobalPluginData;

package/src/client/structuredDataUtils.ts

@@ -0,0 +1,32 @@
+/**
+ * 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 type {PropSidebarBreadcrumbsItem} from '@docusaurus/plugin-content-docs';
+import type {WithContext, BreadcrumbList} from 'schema-dts';
+
+export function useBreadcrumbsStructuredData({
+  breadcrumbs,
+}: {
+  breadcrumbs: PropSidebarBreadcrumbsItem[];
+}): WithContext<BreadcrumbList> {
+  const {siteConfig} = useDocusaurusContext();
+  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: `${siteConfig.url}${breadcrumb.href}`,
+      })),
+  };
+}

package/src/index.ts

@@ -6,6 +6,7 @@
  */
 
 import path from 'path';
+import fs from 'fs-extra';
 import _ from 'lodash';
 import logger from '@docusaurus/logger';
 import {
@@ -63,6 +64,30 @@ import type {LoadContext, Plugin} from '@docusaurus/types';
 import type {DocFile, FullVersion} from './types';
 import type {RuleSetRule} from 'webpack';
 
+// MDX loader is not 100% deterministic, leading to cache invalidation issue
+// This permits to invalidate the MDX loader cache entries when content changes
+// Problem documented here: https://github.com/facebook/docusaurus/pull/10934
+// TODO this is not a perfect solution, find better?
+async function createMdxLoaderDependencyFile({
+  dataDir,
+  options,
+  versionsMetadata,
+}: {
+  dataDir: string;
+  options: PluginOptions;
+  versionsMetadata: VersionMetadata[];
+}): Promise<string | undefined> {
+  const filePath = path.join(dataDir, '__mdx-loader-dependency.json');
+  // the cache is invalidated whenever this file content changes
+  const fileContent = {
+    options,
+    versionsMetadata,
+  };
+  await fs.ensureDir(dataDir);
+  await fs.writeFile(filePath, JSON.stringify(fileContent));
+  return filePath;
+}
+
 export default async function pluginContentDocs(
   context: LoadContext,
   options: PluginOptions,
@@ -107,6 +132,14 @@ export default async function pluginContentDocs(
     return createMDXLoaderRule({
       include: contentDirs,
       options: {
+        dependencies: [
+          await createMdxLoaderDependencyFile({
+            dataDir,
+            options,
+            versionsMetadata,
+          }),
+        ].filter((d): d is string => typeof d === 'string'),
+
         useCrossCompilerCache:
           siteConfig.future.experimental_faster.mdxCrossCompilerCache,
         admonitions: options.admonitions,

package/src/plugin-content-docs.d.ts

@@ -20,7 +20,11 @@ declare module '@docusaurus/plugin-content-docs' {
     TagMetadata,
     TagsPluginOptions,
   } from '@docusaurus/utils';
-  import type {Plugin, LoadContext} from '@docusaurus/types';
+  import type {
+    Plugin,
+    LoadContext,
+    OptionValidationContext,
+  } from '@docusaurus/types';
   import type {Overwrite, Required} from 'utility-types';
 
   export type Assets = {
@@ -559,6 +563,10 @@ declare module '@docusaurus/plugin-content-docs' {
     context: LoadContext,
     options: PluginOptions,
   ): Promise<Plugin<LoadedContent>>;
+
+  export function validateOptions(
+    args: OptionValidationContext<Options | undefined, PluginOptions>,
+  ): PluginOptions;
 }
 
 declare module '@theme/DocItem' {

package/src/versions/files.ts

@@ -75,6 +75,21 @@ export function getDocsDirPathLocalized({
   });
 }
 
+export function getPluginDirPathLocalized({
+  localizationDir,
+  pluginId,
+}: {
+  localizationDir: string;
+  pluginId: string;
+}): string {
+  return getPluginI18nPath({
+    localizationDir,
+    pluginName: 'docusaurus-plugin-content-docs',
+    pluginId,
+    subPaths: [],
+  });
+}
+
 /** `community` => `[siteDir]/community_versions.json` */
 export function getVersionsFilePath(siteDir: string, pluginId: string): string {
   return path.join(siteDir, addPluginIdPrefix(VERSIONS_JSON_FILE, pluginId));