feat(v1): add deletedDocs config to escape from versioning fallback (#2955)

* feat: support for deletedDocs in siteConfig

fixes #2429

* docs: document deletedDocs option

* feat: allow array in deletedDocs config

* docs: clarify deletedDocs version formatting

packages/docusaurus-1.x/lib/server/readMetadata.js

@@ -25,6 +25,15 @@ const utils = require('./utils.js');
 
 const docsPart = `${siteConfig.docsUrl ? `${siteConfig.docsUrl}/` : ''}`;
 
+// Get a list of all IDs that have been deleted in any version.
+// We will assume these should not be in the current/next version.
+const allDeletedIds = new Set();
+if (siteConfig.deletedDocs) {
+  Object.values(siteConfig.deletedDocs).forEach((idList) => {
+    idList.forEach((id) => allDeletedIds.add(id));
+  });
+}
+
 const SupportedHeaderFields = new Set([
   'id',
   'title',
@@ -238,6 +247,12 @@ function generateMetadataDocs() {
           return;
         }
         const metadata = res.metadata;
+        if (
+          allDeletedIds.has(metadata.id) ||
+          (metadata.original_id && allDeletedIds.has(metadata.original_id))
+        ) {
+          return;
+        }
         metadatas[metadata.id] = metadata;
 
         // create a default list of documents for each enabled language based on docs in English
@@ -290,6 +305,12 @@ function generateMetadataDocs() {
           return;
         }
         const metadata = res.metadata;
+        if (
+          allDeletedIds.has(metadata.id) ||
+          (metadata.original_id && allDeletedIds.has(metadata.original_id))
+        ) {
+          return;
+        }
         metadatas[metadata.id] = metadata;
       }
     });

packages/docusaurus-1.x/lib/server/versionFallback.js

@@ -115,15 +115,46 @@ function docVersion(id, reqVersion) {
   // iterate through versions until a version less than or equal to the requested
   // is found, then check if that version has an available file to use
   let requestedFound = false;
+  let availableVersion = null;
+  let deletedDocs = null;
+  if (siteConfig.deletedDocs) {
+    // Config file may have either Array or Set for each version. Convert
+    // all to Set to make the check faster in the versions loop below.
+    deletedDocs = {};
+    Object.keys(siteConfig.deletedDocs).forEach((deletedDocVersion) => {
+      deletedDocs[deletedDocVersion] = new Set(
+        siteConfig.deletedDocs[deletedDocVersion],
+      );
+    });
+  }
   for (let i = 0; i < versions.length; i++) {
     if (versions[i] === reqVersion) {
       requestedFound = true;
     }
-    if (requestedFound && available[id].has(versions[i])) {
-      return versions[i];
+    if (requestedFound) {
+      // If this ID is deleted as of any version equal to or prior to
+      // the requested, return null.
+      if (
+        deletedDocs &&
+        deletedDocs[versions[i]] &&
+        deletedDocs[versions[i]].has(id)
+      ) {
+        return null;
+      }
+      if (!availableVersion && available[id].has(versions[i])) {
+        availableVersion = versions[i];
+        // Note the fallback version but keep looping in case this ID
+        // was deleted as of a previous version.
+        //
+        // If `deletedDocs` config isn't used, we can return immediately
+        // and avoid unnecessary looping.
+        if (!deletedDocs) {
+          break;
+        }
+      }
     }
   }
-  return null;
+  return availableVersion;
 }
 
 // returns whether a given file has content that differ from the