fix(v2): navbar doc item should allow older versions to not contain the target doc, as long as the lastVersion contains it (#4985)

packages/docusaurus-plugin-content-docs/src/plugin-content-docs.d.ts

@@ -43,6 +43,11 @@ declare module '@docusaurus/plugin-content-docs-types' {
   export type PropSidebars = {
     [sidebarId: string]: PropSidebarItem[];
   };
+
+  export type {
+    GlobalVersion as GlobalDataVersion,
+    GlobalDoc as GlobalDataDoc,
+  } from './types';
 }
 
 declare module '@theme/DocItem' {

packages/docusaurus-theme-classic/src/theme/NavbarItem/DocNavbarItem.tsx

@@ -11,6 +11,29 @@ import {useLatestVersion, useActiveDocContext} from '@theme/hooks/useDocs';
 import clsx from 'clsx';
 import type {Props} from '@theme/NavbarItem/DocNavbarItem';
 import {useDocsPreferredVersion} from '@docusaurus/theme-common';
+import type {
+  GlobalDataVersion,
+  GlobalDataDoc,
+} from '@docusaurus/plugin-content-docs-types';
+
+function getDocInVersions(versions: GlobalDataVersion[], docId: string) {
+  // vanilla-js flatten, TODO replace soon by ES flat() / flatMap()
+  const allDocs: GlobalDataDoc[] = [].concat(
+    ...versions.map((version) => version.docs),
+  );
+
+  const doc = allDocs.find((versionDoc) => versionDoc.id === docId);
+  if (!doc) {
+    const docIds = allDocs.map((versionDoc) => versionDoc.id).join('\n- ');
+    throw new Error(
+      `DocNavbarItem: couldn't find any doc with id "${docId}" in version${
+        versions.length ? 's' : ''
+      } ${versions.map((version) => version.name).join(', ')}".
+Available doc ids are:\n- ${docIds}`,
+    );
+  }
+  return doc;
+}
 
 export default function DocNavbarItem({
   docId,
@@ -23,16 +46,13 @@ export default function DocNavbarItem({
   const {preferredVersion} = useDocsPreferredVersion(docsPluginId);
   const latestVersion = useLatestVersion(docsPluginId);
 
-  const version = activeVersion ?? preferredVersion ?? latestVersion;
+  // Versions used to look for the doc to link to, ordered + no duplicate
-
+  const versions: GlobalDataVersion[] = [
-  const doc = version.docs.find((versionDoc) => versionDoc.id === docId);
+    ...new Set(
-  if (!doc) {
+      [activeVersion, preferredVersion, latestVersion].filter(Boolean),
-    const docIds = version.docs.map((versionDoc) => versionDoc.id).join('\n- ');
+    ),
-    throw new Error(
+  ];
-      `DocNavbarItem: couldn't find any doc with "${docId}" id in version "${version.name}".
+  const doc = getDocInVersions(versions, docId);
-Available doc ids:\n- ${docIds}`,
-    );
-  }
 
   return (
     <DefaultNavbarItem