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

docs/api-site-config.md

@@ -128,6 +128,26 @@ customDocsPath: 'website-docs';
 
 The default version for the site to be shown. If this is not set, the latest version will be shown.
 
+#### `deletedDocs` [object]
+
+Even if you delete the main file for a documentation page and delete it from your sidebar, the page will still be created for every version and for the current version due to [fallback functionality](versioning#fallback-functionality). This can lead to confusion if people find the documentation by searching and it appears to be something relevant to a particular version but actually is not.
+
+To force removal of content beginning with a certain version (including for current/next), add a `deletedDocs` object to your config, where each key is a version and the value is an array of document IDs that should not be generated for that version and all later versions.
+
+Example:
+
+```js
+{
+  deletedDocs: {
+    "2.0.0": [
+      "tagging"
+    ]
+  }
+}
+```
+
+The version keys must match those in `versions.json`. Assuming the versions list in `versions.json` is `["3.0.0", "2.0.0", "1.1.0", "1.0.0"]`, the `docs/1.0.0/tagging` and `docs/1.1.0/tagging` URLs will work but `docs/2.0.0/tagging`, `docs/3.0.0/tagging`, and `docs/tagging` will not. The files and folders for those versions will not be generated during the build.
+
 #### `docsUrl` [string]
 
 The base URL for all docs file. Set this field to `''` to remove the `docs` prefix of the documentation URL. If unset, it is defaulted to `docs`.

docs/guides-versioning.md

@@ -72,6 +72,8 @@ Only files in the `docs` directory and sidebar files that differ from those of t
 
 For example, a document with the original id `doc1` exists for the latest version, `1.0.0`, and has the same content as the document with the id `doc1` in the `docs` directory. When a new version `2.0.0` is created, the file for `doc1` will not be copied into `versioned_docs/version-2.0.0/`. There will still be a page for `docs/2.0.0/doc1.html`, but it will use the file from version `1.0.0`.
 
+Because of the way this fallback works, pages that you delete are not really deleted from the website unless you tell Docusaurus to skip fallback after a certain version. To do this, use the [`deletedDocs`](api-site-config.md#deleteddocs-object) option in `siteConfig.js`.
+
 ## Renaming Existing Versions
 
 To rename an existing version number to something else, first make sure the following script is in your `package.json` file:

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,16 +115,47 @@ 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 availableVersion;
+}
 
 // returns whether a given file has content that differ from the
 // document with the given id