@docusaurus/plugin-content-docs 3.8.1-canary-6342 → 3.8.1-canary-6345

package/lib/versions/loadVersion.d.ts

@@ -7,9 +7,11 @@
 import { type DocEnv } from '../docs';
 import type { LoadedVersion, PluginOptions, VersionMetadata } from '@docusaurus/plugin-content-docs';
 import type { LoadContext } from '@docusaurus/types';
-export declare function loadVersion({ context, options, versionMetadata, env, }: {
+type LoadVersionParams = {
     context: LoadContext;
     options: PluginOptions;
     versionMetadata: VersionMetadata;
     env: DocEnv;
-}): Promise<LoadedVersion>;
+};
+export declare function loadVersion(params: LoadVersionParams): Promise<LoadedVersion>;
+export {};

package/lib/versions/loadVersion.js

@@ -16,74 +16,105 @@ const logger_1 = tslib_1.__importDefault(require("@docusaurus/logger"));
 const docs_1 = require("../docs");
 const sidebars_1 = require("../sidebars");
 const utils_2 = require("../sidebars/utils");
-async function loadVersion({ context, options, versionMetadata, env, }) {
-    const { siteDir } = context;
-    async function loadVersionDocsBase(tagsFile) {
-        const docFiles = await (0, docs_1.readVersionDocs)(versionMetadata, options);
-        if (docFiles.length === 0) {
-            throw new Error(`Docs version "${versionMetadata.versionName}" has no docs! At least one doc should exist at "${path_1.default.relative(siteDir, versionMetadata.contentPath)}".`);
-        }
-        function processVersionDoc(docFile) {
-            return (0, docs_1.processDocMetadata)({
-                docFile,
-                versionMetadata,
-                context,
-                options,
-                env,
-                tagsFile,
-            });
-        }
-        return Promise.all(docFiles.map(processVersionDoc));
+function ensureNoDuplicateDocId(docs) {
+    const duplicatesById = lodash_1.default.chain(docs)
+        .groupBy((d) => d.id)
+        .pickBy((group) => group.length > 1)
+        .value();
+    const duplicateIdEntries = Object.entries(duplicatesById);
+    if (duplicateIdEntries.length) {
+        const idMessages = duplicateIdEntries
+            .map(([id, duplicateDocs]) => {
+            return logger_1.default.interpolate `- code=${id} found in number=${duplicateDocs.length} docs:
+  - ${duplicateDocs
+                .map((d) => (0, utils_1.aliasedSitePathToRelativePath)(d.source))
+                .join('\n  - ')}`;
+        })
+            .join('\n\n');
+        const message = `The docs plugin found docs sharing the same id:
+\n${idMessages}\n
+Docs should have distinct ids.
+In case of conflict, you can rename the docs file, or use the ${logger_1.default.code('id')} front matter to assign an explicit distinct id to each doc.
+    `;
+        throw new Error(message);
     }
-    async function doLoadVersion() {
-        const tagsFile = await (0, utils_validation_1.getTagsFile)({
-            contentPaths: versionMetadata,
-            tags: options.tags,
-        });
-        const docsBase = await loadVersionDocsBase(tagsFile);
-        // TODO we only ever need draftIds in further code, not full draft items
-        // To simplify and prevent mistakes, avoid exposing draft
-        // replace draft=>draftIds in content loaded
-        const [drafts, docs] = lodash_1.default.partition(docsBase, (doc) => doc.draft);
-        const sidebars = await (0, sidebars_1.loadSidebars)(versionMetadata.sidebarFilePath, {
-            sidebarItemsGenerator: options.sidebarItemsGenerator,
-            numberPrefixParser: options.numberPrefixParser,
-            docs,
-            drafts,
-            version: versionMetadata,
-            sidebarOptions: {
-                sidebarCollapsed: options.sidebarCollapsed,
-                sidebarCollapsible: options.sidebarCollapsible,
-            },
-            categoryLabelSlugger: (0, utils_1.createSlugger)(),
-        });
-        const sidebarsUtils = (0, utils_2.createSidebarsUtils)(sidebars);
-        const docsById = (0, docs_1.createDocsByIdIndex)(docs);
-        const allDocIds = Object.keys(docsById);
-        sidebarsUtils.checkLegacyVersionedSidebarNames({
-            sidebarFilePath: versionMetadata.sidebarFilePath,
-            versionMetadata,
-        });
-        sidebarsUtils.checkSidebarsDocIds({
-            allDocIds,
-            sidebarFilePath: versionMetadata.sidebarFilePath,
+}
+async function loadVersionDocsBase({ tagsFile, context, options, versionMetadata, env, }) {
+    const docFiles = await (0, docs_1.readVersionDocs)(versionMetadata, options);
+    if (docFiles.length === 0) {
+        throw new Error(`Docs version "${versionMetadata.versionName}" has no docs! At least one doc should exist at "${path_1.default.relative(context.siteDir, versionMetadata.contentPath)}".`);
+    }
+    function processVersionDoc(docFile) {
+        return (0, docs_1.processDocMetadata)({
+            docFile,
             versionMetadata,
+            context,
+            options,
+            env,
+            tagsFile,
         });
-        return {
-            ...versionMetadata,
-            docs: (0, docs_1.addDocNavigation)({
-                docs,
-                sidebarsUtils,
-            }),
-            drafts,
-            sidebars,
-        };
     }
+    const docs = await Promise.all(docFiles.map(processVersionDoc));
+    ensureNoDuplicateDocId(docs);
+    return docs;
+}
+async function doLoadVersion({ context, options, versionMetadata, env, }) {
+    const tagsFile = await (0, utils_validation_1.getTagsFile)({
+        contentPaths: versionMetadata,
+        tags: options.tags,
+    });
+    const docsBase = await loadVersionDocsBase({
+        tagsFile,
+        context,
+        options,
+        versionMetadata,
+        env,
+    });
+    // TODO we only ever need draftIds in further code, not full draft items
+    // To simplify and prevent mistakes, avoid exposing draft
+    // replace draft=>draftIds in content loaded
+    const [drafts, docs] = lodash_1.default.partition(docsBase, (doc) => doc.draft);
+    const sidebars = await (0, sidebars_1.loadSidebars)(versionMetadata.sidebarFilePath, {
+        sidebarItemsGenerator: options.sidebarItemsGenerator,
+        numberPrefixParser: options.numberPrefixParser,
+        docs,
+        drafts,
+        version: versionMetadata,
+        sidebarOptions: {
+            sidebarCollapsed: options.sidebarCollapsed,
+            sidebarCollapsible: options.sidebarCollapsible,
+        },
+        categoryLabelSlugger: (0, utils_1.createSlugger)(),
+    });
+    const sidebarsUtils = (0, utils_2.createSidebarsUtils)(sidebars);
+    const docsById = (0, docs_1.createDocsByIdIndex)(docs);
+    const allDocIds = Object.keys(docsById);
+    sidebarsUtils.checkLegacyVersionedSidebarNames({
+        sidebarFilePath: versionMetadata.sidebarFilePath,
+        versionMetadata,
+    });
+    sidebarsUtils.checkSidebarsDocIds({
+        allDocIds,
+        sidebarFilePath: versionMetadata.sidebarFilePath,
+        versionMetadata,
+    });
+    return {
+        ...versionMetadata,
+        docs: (0, docs_1.addDocNavigation)({
+            docs,
+            sidebarsUtils,
+        }),
+        drafts,
+        sidebars,
+    };
+}
+async function loadVersion(params) {
     try {
-        return await doLoadVersion();
+        return await doLoadVersion(params);
     }
     catch (err) {
-        logger_1.default.error `Loading of version failed for version name=${versionMetadata.versionName}`;
+        // TODO use error cause (but need to refactor many tests)
+        logger_1.default.error `Loading of version failed for version name=${params.versionMetadata.versionName}`;
         throw err;
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/plugin-content-docs",
-  "version": "3.8.1-canary-6342",
+  "version": "3.8.1-canary-6345",
   "description": "Docs plugin for Docusaurus.",
   "main": "lib/index.js",
   "sideEffects": false,
@@ -35,15 +35,15 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/core": "3.8.1-canary-6342",
-    "@docusaurus/logger": "3.8.1-canary-6342",
-    "@docusaurus/mdx-loader": "3.8.1-canary-6342",
-    "@docusaurus/module-type-aliases": "3.8.1-canary-6342",
-    "@docusaurus/theme-common": "3.8.1-canary-6342",
-    "@docusaurus/types": "3.8.1-canary-6342",
-    "@docusaurus/utils": "3.8.1-canary-6342",
-    "@docusaurus/utils-common": "3.8.1-canary-6342",
-    "@docusaurus/utils-validation": "3.8.1-canary-6342",
+    "@docusaurus/core": "3.8.1-canary-6345",
+    "@docusaurus/logger": "3.8.1-canary-6345",
+    "@docusaurus/mdx-loader": "3.8.1-canary-6345",
+    "@docusaurus/module-type-aliases": "3.8.1-canary-6345",
+    "@docusaurus/theme-common": "3.8.1-canary-6345",
+    "@docusaurus/types": "3.8.1-canary-6345",
+    "@docusaurus/utils": "3.8.1-canary-6345",
+    "@docusaurus/utils-common": "3.8.1-canary-6345",
+    "@docusaurus/utils-validation": "3.8.1-canary-6345",
     "@types/react-router-config": "^5.0.7",
     "combine-promises": "^1.1.0",
     "fs-extra": "^11.1.1",
@@ -67,5 +67,5 @@
   "engines": {
     "node": ">=18.0"
   },
-  "gitHead": "42b5935e8d58a11d95a3fe89b28504bb63b1d6a5"
+  "gitHead": "3e07b014298c3b0936d84a6544eff9fa5d0966df"
 }

package/src/versions/loadVersion.ts

@@ -7,7 +7,7 @@
 
 import path from 'path';
 import _ from 'lodash';
-import {createSlugger} from '@docusaurus/utils';
+import {aliasedSitePathToRelativePath, createSlugger} from '@docusaurus/utils';
 import {getTagsFile} from '@docusaurus/utils-validation';
 import logger from '@docusaurus/logger';
 import {
@@ -29,102 +29,151 @@ import type {
 import type {DocFile} from '../types';
 import type {LoadContext} from '@docusaurus/types';
 
-export async function loadVersion({
-  context,
-  options,
-  versionMetadata,
-  env,
-}: {
+type LoadVersionParams = {
   context: LoadContext;
   options: PluginOptions;
   versionMetadata: VersionMetadata;
   env: DocEnv;
-}): Promise<LoadedVersion> {
-  const {siteDir} = context;
-
-  async function loadVersionDocsBase(
-    tagsFile: TagsFile | null,
-  ): Promise<DocMetadataBase[]> {
-    const docFiles = await readVersionDocs(versionMetadata, options);
-    if (docFiles.length === 0) {
-      throw new Error(
-        `Docs version "${
-          versionMetadata.versionName
-        }" has no docs! At least one doc should exist at "${path.relative(
-          siteDir,
-          versionMetadata.contentPath,
-        )}".`,
-      );
-    }
-    function processVersionDoc(docFile: DocFile) {
-      return processDocMetadata({
-        docFile,
-        versionMetadata,
-        context,
-        options,
-        env,
-        tagsFile,
-      });
-    }
-    return Promise.all(docFiles.map(processVersionDoc));
+};
+
+function ensureNoDuplicateDocId(docs: DocMetadataBase[]): void {
+  const duplicatesById = _.chain(docs)
+    .groupBy((d) => d.id)
+    .pickBy((group) => group.length > 1)
+    .value();
+
+  const duplicateIdEntries = Object.entries(duplicatesById);
+
+  if (duplicateIdEntries.length) {
+    const idMessages = duplicateIdEntries
+      .map(([id, duplicateDocs]) => {
+        return logger.interpolate`- code=${id} found in number=${
+          duplicateDocs.length
+        } docs:
+  - ${duplicateDocs
+    .map((d) => aliasedSitePathToRelativePath(d.source))
+    .join('\n  - ')}`;
+      })
+      .join('\n\n');
+
+    const message = `The docs plugin found docs sharing the same id:
+\n${idMessages}\n
+Docs should have distinct ids.
+In case of conflict, you can rename the docs file, or use the ${logger.code(
+      'id',
+    )} front matter to assign an explicit distinct id to each doc.
+    `;
+
+    throw new Error(message);
   }
+}
 
-  async function doLoadVersion(): Promise<LoadedVersion> {
-    const tagsFile = await getTagsFile({
-      contentPaths: versionMetadata,
-      tags: options.tags,
+async function loadVersionDocsBase({
+  tagsFile,
+  context,
+  options,
+  versionMetadata,
+  env,
+}: LoadVersionParams & {
+  tagsFile: TagsFile | null;
+}): Promise<DocMetadataBase[]> {
+  const docFiles = await readVersionDocs(versionMetadata, options);
+  if (docFiles.length === 0) {
+    throw new Error(
+      `Docs version "${
+        versionMetadata.versionName
+      }" has no docs! At least one doc should exist at "${path.relative(
+        context.siteDir,
+        versionMetadata.contentPath,
+      )}".`,
+    );
+  }
+  function processVersionDoc(docFile: DocFile) {
+    return processDocMetadata({
+      docFile,
+      versionMetadata,
+      context,
+      options,
+      env,
+      tagsFile,
     });
+  }
+  const docs = await Promise.all(docFiles.map(processVersionDoc));
+  ensureNoDuplicateDocId(docs);
+  return docs;
+}
 
-    const docsBase: DocMetadataBase[] = await loadVersionDocsBase(tagsFile);
+async function doLoadVersion({
+  context,
+  options,
+  versionMetadata,
+  env,
+}: LoadVersionParams): Promise<LoadedVersion> {
+  const tagsFile = await getTagsFile({
+    contentPaths: versionMetadata,
+    tags: options.tags,
+  });
 
-    // TODO we only ever need draftIds in further code, not full draft items
-    // To simplify and prevent mistakes, avoid exposing draft
-    // replace draft=>draftIds in content loaded
-    const [drafts, docs] = _.partition(docsBase, (doc) => doc.draft);
+  const docsBase: DocMetadataBase[] = await loadVersionDocsBase({
+    tagsFile,
+    context,
+    options,
+    versionMetadata,
+    env,
+  });
 
-    const sidebars = await loadSidebars(versionMetadata.sidebarFilePath, {
-      sidebarItemsGenerator: options.sidebarItemsGenerator,
-      numberPrefixParser: options.numberPrefixParser,
-      docs,
-      drafts,
-      version: versionMetadata,
-      sidebarOptions: {
-        sidebarCollapsed: options.sidebarCollapsed,
-        sidebarCollapsible: options.sidebarCollapsible,
-      },
-      categoryLabelSlugger: createSlugger(),
-    });
+  // TODO we only ever need draftIds in further code, not full draft items
+  // To simplify and prevent mistakes, avoid exposing draft
+  // replace draft=>draftIds in content loaded
+  const [drafts, docs] = _.partition(docsBase, (doc) => doc.draft);
 
-    const sidebarsUtils = createSidebarsUtils(sidebars);
+  const sidebars = await loadSidebars(versionMetadata.sidebarFilePath, {
+    sidebarItemsGenerator: options.sidebarItemsGenerator,
+    numberPrefixParser: options.numberPrefixParser,
+    docs,
+    drafts,
+    version: versionMetadata,
+    sidebarOptions: {
+      sidebarCollapsed: options.sidebarCollapsed,
+      sidebarCollapsible: options.sidebarCollapsible,
+    },
+    categoryLabelSlugger: createSlugger(),
+  });
 
-    const docsById = createDocsByIdIndex(docs);
-    const allDocIds = Object.keys(docsById);
+  const sidebarsUtils = createSidebarsUtils(sidebars);
 
-    sidebarsUtils.checkLegacyVersionedSidebarNames({
-      sidebarFilePath: versionMetadata.sidebarFilePath as string,
-      versionMetadata,
-    });
-    sidebarsUtils.checkSidebarsDocIds({
-      allDocIds,
-      sidebarFilePath: versionMetadata.sidebarFilePath as string,
-      versionMetadata,
-    });
+  const docsById = createDocsByIdIndex(docs);
+  const allDocIds = Object.keys(docsById);
 
-    return {
-      ...versionMetadata,
-      docs: addDocNavigation({
-        docs,
-        sidebarsUtils,
-      }),
-      drafts,
-      sidebars,
-    };
-  }
+  sidebarsUtils.checkLegacyVersionedSidebarNames({
+    sidebarFilePath: versionMetadata.sidebarFilePath as string,
+    versionMetadata,
+  });
+  sidebarsUtils.checkSidebarsDocIds({
+    allDocIds,
+    sidebarFilePath: versionMetadata.sidebarFilePath as string,
+    versionMetadata,
+  });
+
+  return {
+    ...versionMetadata,
+    docs: addDocNavigation({
+      docs,
+      sidebarsUtils,
+    }),
+    drafts,
+    sidebars,
+  };
+}
 
+export async function loadVersion(
+  params: LoadVersionParams,
+): Promise<LoadedVersion> {
   try {
-    return await doLoadVersion();
+    return await doLoadVersion(params);
   } catch (err) {
-    logger.error`Loading of version failed for version name=${versionMetadata.versionName}`;
+    // TODO use error cause (but need to refactor many tests)
+    logger.error`Loading of version failed for version name=${params.versionMetadata.versionName}`;
     throw err;
   }
 }