diff --git a/docs/api-site-config.md b/docs/api-site-config.md index b345ea97ab50..77b9e99c32d3 100644 --- a/docs/api-site-config.md +++ b/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`. diff --git a/docs/guides-versioning.md b/docs/guides-versioning.md index c0381cc2fc23..a84c16e8f654 100644 --- a/docs/guides-versioning.md +++ b/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: diff --git a/packages/docusaurus-1.x/lib/server/readMetadata.js b/packages/docusaurus-1.x/lib/server/readMetadata.js index a7c95e28ba25..538c88a72ff9 100644 --- a/packages/docusaurus-1.x/lib/server/readMetadata.js +++ b/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; } }); diff --git a/packages/docusaurus-1.x/lib/server/versionFallback.js b/packages/docusaurus-1.x/lib/server/versionFallback.js index cb7c88c6cac7..64df0f3f9868 100644 --- a/packages/docusaurus-1.x/lib/server/versionFallback.js +++ b/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