From 3fca196935dc6c1c02bb1c5e58d5df52854d8aec Mon Sep 17 00:00:00 2001 From: Eric Dobbertin Date: Wed, 17 Jun 2020 14:17:43 -0500 Subject: [PATCH 1/4] feat: support for deletedDocs in siteConfig fixes #2429 --- .../docusaurus-1.x/lib/server/readMetadata.js | 21 +++++++++++++++ .../lib/server/versionFallback.js | 27 ++++++++++++++++--- 2 files changed, 45 insertions(+), 3 deletions(-) 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..7137886a7bd1 100644 --- a/packages/docusaurus-1.x/lib/server/versionFallback.js +++ b/packages/docusaurus-1.x/lib/server/versionFallback.js @@ -115,15 +115,36 @@ 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; + const {deletedDocs} = siteConfig; 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 From 2c9d26ea7442dc251e19f7ae8edb34092a5811d1 Mon Sep 17 00:00:00 2001 From: Eric Dobbertin Date: Wed, 17 Jun 2020 14:18:07 -0500 Subject: [PATCH 2/4] docs: document deletedDocs option --- docs/api-site-config.md | 20 ++++++++++++++++++++ docs/guides-versioning.md | 2 ++ 2 files changed, 22 insertions(+) diff --git a/docs/api-site-config.md b/docs/api-site-config.md index b345ea97ab50..8a2c792db33a 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 a `Set` of document IDs that should not be generated for that version and all later versions. + +Example: + +```js +{ + deletedDocs: { + "2.0.0": new Set([ + "tagging" + ]) + } +} +``` + +Assuming the versions list 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: From 050c41a30dbbe2baf17dfc4fa3550d693b2d927f Mon Sep 17 00:00:00 2001 From: Eric Dobbertin Date: Wed, 24 Jun 2020 10:12:54 -0500 Subject: [PATCH 3/4] feat: allow array in deletedDocs config --- docs/api-site-config.md | 6 +++--- .../docusaurus-1.x/lib/server/versionFallback.js | 12 +++++++++++- 2 files changed, 14 insertions(+), 4 deletions(-) diff --git a/docs/api-site-config.md b/docs/api-site-config.md index 8a2c792db33a..01df1db384f6 100644 --- a/docs/api-site-config.md +++ b/docs/api-site-config.md @@ -132,16 +132,16 @@ The default version for the site to be shown. If this is not set, the latest ver 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 a `Set` of document IDs that should not be generated for that version and all later versions. +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 or `Set` of document IDs that should not be generated for that version and all later versions. Example: ```js { deletedDocs: { - "2.0.0": new Set([ + "2.0.0": [ "tagging" - ]) + ] } } ``` diff --git a/packages/docusaurus-1.x/lib/server/versionFallback.js b/packages/docusaurus-1.x/lib/server/versionFallback.js index 7137886a7bd1..64df0f3f9868 100644 --- a/packages/docusaurus-1.x/lib/server/versionFallback.js +++ b/packages/docusaurus-1.x/lib/server/versionFallback.js @@ -116,7 +116,17 @@ function docVersion(id, reqVersion) { // is found, then check if that version has an available file to use let requestedFound = false; let availableVersion = null; - const {deletedDocs} = siteConfig; + 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; From a41782b52d6c1f4c46e35d36ad0892b5690f4e46 Mon Sep 17 00:00:00 2001 From: Eric Dobbertin Date: Thu, 25 Jun 2020 10:18:11 -0500 Subject: [PATCH 4/4] docs: clarify deletedDocs version formatting --- docs/api-site-config.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/api-site-config.md b/docs/api-site-config.md index 01df1db384f6..77b9e99c32d3 100644 --- a/docs/api-site-config.md +++ b/docs/api-site-config.md @@ -132,7 +132,7 @@ The default version for the site to be shown. If this is not set, the latest ver 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 or `Set` of document IDs that should not be generated for that version and all later versions. +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: @@ -146,7 +146,7 @@ Example: } ``` -Assuming the versions list 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. +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]