fix(docs): prevent docs ids conflicts within a version (#11251)

packages/docusaurus-plugin-content-docs/src/versions/__tests__/__fixtures__/site-broken-versions/versioned_docs/version-with-id-conflicts/frontMatter/deeply/doc.md

@@ -0,0 +1,4 @@
+
+# Hello
+
+World

packages/docusaurus-plugin-content-docs/src/versions/__tests__/__fixtures__/site-broken-versions/versioned_docs/version-with-id-conflicts/frontMatter/deeply/nested/whatever.md

@@ -0,0 +1,7 @@
+---
+id: doc
+---
+
+# Hello
+
+World

packages/docusaurus-plugin-content-docs/src/versions/__tests__/__fixtures__/site-broken-versions/versioned_docs/version-with-id-conflicts/frontMatter/doc.md

@@ -0,0 +1,7 @@
+---
+# no id but should conflict due to the name anyway
+---
+
+# Hello
+
+World

packages/docusaurus-plugin-content-docs/src/versions/__tests__/__fixtures__/site-broken-versions/versioned_docs/version-with-id-conflicts/frontMatter/doc1.md

@@ -0,0 +1,7 @@
+---
+id: doc
+---
+
+# Hello
+
+World

packages/docusaurus-plugin-content-docs/src/versions/__tests__/__fixtures__/site-broken-versions/versioned_docs/version-with-id-conflicts/frontMatter/doc2.md

@@ -0,0 +1,7 @@
+---
+id: doc
+---
+
+# Hello
+
+World

packages/docusaurus-plugin-content-docs/src/versions/__tests__/__fixtures__/site-broken-versions/versioned_docs/version-with-id-conflicts/number-prefix/1-doc.md

@@ -0,0 +1,3 @@
+# Hello
+
+World

packages/docusaurus-plugin-content-docs/src/versions/__tests__/__fixtures__/site-broken-versions/versioned_docs/version-with-id-conflicts/number-prefix/2-doc.md

@@ -0,0 +1,7 @@
+---
+id: doc
+---
+
+# Hello
+
+World

packages/docusaurus-plugin-content-docs/src/versions/__tests__/__fixtures__/site-broken-versions/versioned_docs/version-with-id-conflicts/number-prefix/deeply/1-doc.md

@@ -0,0 +1,3 @@
+# Hello
+
+World

packages/docusaurus-plugin-content-docs/src/versions/__tests__/__fixtures__/site-broken-versions/versioned_docs/version-with-id-conflicts/number-prefix/deeply/nested/2-doc.md

@@ -0,0 +1,3 @@
+# Hello
+
+World

packages/docusaurus-plugin-content-docs/src/versions/__tests__/__fixtures__/site-broken-versions/versioned_docs/version-with-id-conflicts/number-prefix/deeply/nested/3-doc.md

@@ -0,0 +1,3 @@
+# Hello
+
+World

packages/docusaurus-plugin-content-docs/src/versions/__tests__/__fixtures__/site-broken-versions/versioned_docs/version-with-id-conflicts/number-prefix/distinct-frontMatter-id/1-doc.md

@@ -0,0 +1,7 @@
+---
+id: doc-1
+---
+
+# Hello
+
+World

packages/docusaurus-plugin-content-docs/src/versions/__tests__/__fixtures__/site-broken-versions/versioned_docs/version-with-id-conflicts/number-prefix/distinct-frontMatter-id/2-doc.md

@@ -0,0 +1,7 @@
+---
+id: doc-2
+---
+
+# Hello
+
+World

packages/docusaurus-plugin-content-docs/src/versions/__tests__/__fixtures__/site-broken-versions/versioned_docs/version-with-id-conflicts/number-prefix/distinct-frontMatter-id/3-doc.md

@@ -0,0 +1,7 @@
+---
+id: doc-3
+---
+
+# Hello
+
+World

packages/docusaurus-plugin-content-docs/src/versions/__tests__/__fixtures__/site-broken-versions/versions.json

@@ -0,0 +1,3 @@
+[
+  "with-id-conflicts"
+]

packages/docusaurus-plugin-content-docs/src/versions/__tests__/__fixtures__/site-minimal/docs/hello.md

@@ -0,0 +1,4 @@
+
+# Hello
+
+World

packages/docusaurus-plugin-content-docs/src/versions/__tests__/__snapshots__/loadVersion.test.ts.snap

@@ -1,12 +1,12 @@
 // Jest Snapshot v1, https://goo.gl/fbAQLP
 
-exports[`minimal site can load current version 1`] = `
+exports[`loadVersion minimal site can load current version 1`] = `
 {
   "badge": false,
   "banner": null,
   "className": "docs-version-current",
-  "contentPath": "<PROJECT_ROOT>/packages/docusaurus-plugin-content-docs/src/versions/__tests__/__fixtures__/minimal-site/docs",
+  "contentPath": "<PROJECT_ROOT>/packages/docusaurus-plugin-content-docs/src/versions/__tests__/__fixtures__/site-minimal/docs",
-  "contentPathLocalized": "<PROJECT_ROOT>/packages/docusaurus-plugin-content-docs/src/versions/__tests__/__fixtures__/minimal-site/i18n/en/docusaurus-plugin-content-docs/current",
+  "contentPathLocalized": "<PROJECT_ROOT>/packages/docusaurus-plugin-content-docs/src/versions/__tests__/__fixtures__/site-minimal/i18n/en/docusaurus-plugin-content-docs/current",
   "docs": [
     {
       "description": "World",

packages/docusaurus-plugin-content-docs/src/versions/__tests__/loadVersion.test.ts

@@ -22,12 +22,10 @@ const DefaultI18N: I18n = {
   localeConfigs: {},
 };
 
-describe('minimal site', () => {
+async function siteFixture(fixture: string) {
-  async function loadSite() {
+  const siteDir = path.resolve(path.join(__dirname, './__fixtures__', fixture));
-    const siteDir = path.resolve(
-      path.join(__dirname, './__fixtures__', 'minimal-site'),
-    );
   const options: PluginOptions = fromPartial<PluginOptions>({
+    id: 'default',
     ...DEFAULT_OPTIONS,
   });
   const context = fromPartial<LoadContext>({
@@ -41,33 +39,79 @@ describe('minimal site', () => {
       },
     },
   });
-    return {
-      siteDir,
-      options,
-      context,
-    };
-  }
 
-  it('can load current version', async () => {
+  const versions = await readVersionsMetadata({
-    const {options, context} = await loadSite();
-
-    const versionsMetadata = await readVersionsMetadata({
     options,
     context,
   });
 
-    expect(versionsMetadata).toHaveLength(1);
+  return {
-    expect(versionsMetadata[0]!.versionName).toBe('current');
+    siteDir,
+    options,
+    context,
+    versions,
+  };
+}
 
-    const versionMetadata = versionsMetadata[0]!;
+describe('loadVersion', () => {
+  describe('minimal site', () => {
+    it('can load current version', async () => {
+      const {options, context, versions} = await siteFixture('site-minimal');
+
+      const version = versions[0];
+      expect(version).toBeDefined();
+      expect(version.versionName).toBe('current');
 
       const loadedVersion = loadVersion({
         context,
         options,
-      versionMetadata,
+        versionMetadata: version,
         env: 'production',
       });
 
       await expect(loadedVersion).resolves.toMatchSnapshot();
     });
   });
+
+  describe('site with broken versions', () => {
+    async function loadTestVersion(versionName: string) {
+      const {options, context, versions} = await siteFixture(
+        'site-broken-versions',
+      );
+      const version = versions.find((v) => v.versionName === versionName);
+      if (!version) {
+        throw new Error(`Version '${versionName}' should exist`);
+      }
+      return loadVersion({
+        context,
+        options,
+        versionMetadata: version,
+        env: 'production',
+      });
+    }
+
+    it('rejects version with doc id conflict', async () => {
+      await expect(() => loadTestVersion('with-id-conflicts')).rejects
+        .toThrowErrorMatchingInlineSnapshot(`
+        "The docs plugin found docs sharing the same id:
+
+        - \`frontMatter/doc\` found in 3 docs:
+          - versioned_docs/version-with-id-conflicts/frontMatter/doc.md
+          - versioned_docs/version-with-id-conflicts/frontMatter/doc1.md
+          - versioned_docs/version-with-id-conflicts/frontMatter/doc2.md
+
+        - \`number-prefix/doc\` found in 2 docs:
+          - versioned_docs/version-with-id-conflicts/number-prefix/1-doc.md
+          - versioned_docs/version-with-id-conflicts/number-prefix/2-doc.md
+
+        - \`number-prefix/deeply/nested/doc\` found in 2 docs:
+          - versioned_docs/version-with-id-conflicts/number-prefix/deeply/nested/2-doc.md
+          - versioned_docs/version-with-id-conflicts/number-prefix/deeply/nested/3-doc.md
+
+        Docs should have distinct ids.
+        In case of conflict, you can rename the docs file, or use the \`id\` front matter to assign an explicit distinct id to each doc.
+            "
+      `);
+    });
+  });
+});

packages/docusaurus-plugin-content-docs/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,29 +29,61 @@ import type {
 import type {DocFile} from '../types';
 import type {LoadContext} from '@docusaurus/types';
 
-export async function loadVersion({
+type LoadVersionParams = {
-  context,
-  options,
-  versionMetadata,
-  env,
-}: {
   context: LoadContext;
   options: PluginOptions;
   versionMetadata: VersionMetadata;
   env: DocEnv;
-}): Promise<LoadedVersion> {
+};
-  const {siteDir} = context;
 
-  async function loadVersionDocsBase(
+function ensureNoDuplicateDocId(docs: DocMetadataBase[]): void {
-    tagsFile: TagsFile | null,
+  const duplicatesById = _.chain(docs)
-  ): Promise<DocMetadataBase[]> {
+    .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 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(
-          siteDir,
+        context.siteDir,
         versionMetadata.contentPath,
       )}".`,
     );
@@ -66,16 +98,29 @@ export async function loadVersion({
       tagsFile,
     });
   }
-    return Promise.all(docFiles.map(processVersionDoc));
+  const docs = await Promise.all(docFiles.map(processVersionDoc));
+  ensureNoDuplicateDocId(docs);
+  return docs;
 }
 
-  async function doLoadVersion(): Promise<LoadedVersion> {
+async function doLoadVersion({
+  context,
+  options,
+  versionMetadata,
+  env,
+}: LoadVersionParams): Promise<LoadedVersion> {
   const tagsFile = await getTagsFile({
     contentPaths: versionMetadata,
     tags: options.tags,
   });
 
-    const docsBase: DocMetadataBase[] = await loadVersionDocsBase(tagsFile);
+  const docsBase: DocMetadataBase[] = 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
@@ -121,10 +166,14 @@ export async function loadVersion({
   };
 }
 
+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;
   }
 }

website/_dogfooding/_docs tests/tests/Conflicts/file-name/1-file-name.mdx

@@ -0,0 +1,8 @@
+---
+id: file-name-1
+slug: file-name-1
+---
+
+# File name 1
+
+File name 1

website/_dogfooding/_docs tests/tests/Conflicts/file-name/2-file-name.mdx

@@ -0,0 +1,8 @@
+---
+id: file-name-2
+slug: file-name-2
+---
+
+# File name 2
+
+File name 2

website/_dogfooding/_docs tests/tests/Conflicts/file-name/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "File name conflict",
+  "link": {
+    "type": "generated-index",
+    "title": "File name conflict",
+    "description": "Testing what happens when 2 files have the same name but different position prefixes"
+  }
+}