feat(v2): add disableVersioning config to docs plugin (#2989)

* add disableVersioning config to docs plugin

* fix test

* fix test

packages/docusaurus-plugin-content-docs/src/__tests__/env.test.ts

@@ -24,6 +24,13 @@ describe('loadEnv', () => {
     expect(env.versioning.versions).toStrictEqual(['1.0.1', '1.0.0']);
   });
 
+  test('website with versioning but disabled', () => {
+    const siteDir = path.join(__dirname, '__fixtures__', 'versioned-site');
+    const env = loadEnv(siteDir, {disableVersioning: true});
+    expect(env.versioning.enabled).toBe(false);
+    expect(env.versioning.versions).toStrictEqual([]);
+  });
+
   test('website with invalid versions.json file', () => {
     const siteDir = path.join(__dirname, '__fixtures__', 'versioned-site');
     const mock = jest.spyOn(JSON, 'parse').mockImplementationOnce(() => {

packages/docusaurus-plugin-content-docs/src/__tests__/pluginOptionSchema.test.ts

@@ -39,6 +39,7 @@ describe('normalizeDocsPluginOptions', () => {
       showLastUpdateAuthor: true,
       admonitions: {},
       excludeNextVersionDocs: true,
+      disableVersioning: true,
     };
 
     const {value} = await PluginOptionSchema.validate(userOptions);

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

@@ -26,7 +26,12 @@ export function getVersionsJSONFile(siteDir: string): string {
   return path.join(siteDir, VERSIONS_JSON_FILE);
 }
 
-export default function (siteDir: string): Env {
+type EnvOptions = Partial<{disableVersioning: boolean}>;
+
+export default function (
+  siteDir: string,
+  options: EnvOptions = {disableVersioning: false},
+): Env {
   const versioning: VersioningEnv = {
     enabled: false,
     versions: [],
@@ -37,16 +42,18 @@ export default function (siteDir: string): Env {
 
   const versionsJSONFile = getVersionsJSONFile(siteDir);
   if (fs.existsSync(versionsJSONFile)) {
-    const parsedVersions = JSON.parse(
+    if (!options.disableVersioning) {
-      fs.readFileSync(versionsJSONFile, 'utf8'),
+      const parsedVersions = JSON.parse(
-    );
+        fs.readFileSync(versionsJSONFile, 'utf8'),
-    if (parsedVersions && parsedVersions.length > 0) {
+      );
-      // eslint-disable-next-line prefer-destructuring
+      if (parsedVersions && parsedVersions.length > 0) {
-      versioning.latestVersion = parsedVersions[0];
+        // eslint-disable-next-line prefer-destructuring
-      versioning.enabled = true;
+        versioning.latestVersion = parsedVersions[0];
-      versioning.versions = parsedVersions;
+        versioning.enabled = true;
-      versioning.docsDir = getVersionedDocsDir(siteDir);
+        versioning.versions = parsedVersions;
-      versioning.sidebarsDir = getVersionedSidebarsDir(siteDir);
+        versioning.docsDir = getVersionedDocsDir(siteDir);
+        versioning.sidebarsDir = getVersionedSidebarsDir(siteDir);
+      }
     }
   }
 

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

@@ -95,7 +95,7 @@ export default function pluginContentDocs(
   );
 
   // Versioning.
-  const env = loadEnv(siteDir);
+  const env = loadEnv(siteDir, {disableVersioning: options.disableVersioning});
   const {versioning} = env;
   const {
     versions,

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

@@ -23,6 +23,7 @@ export const DEFAULT_OPTIONS: PluginOptions = {
   showLastUpdateAuthor: false,
   admonitions: {},
   excludeNextVersionDocs: false,
+  disableVersioning: false,
 };
 
 export const PluginOptionSchema = Joi.object({
@@ -51,4 +52,5 @@ export const PluginOptionSchema = Joi.object({
   excludeNextVersionDocs: Joi.bool().default(
     DEFAULT_OPTIONS.excludeNextVersionDocs,
   ),
+  disableVersioning: Joi.bool().default(DEFAULT_OPTIONS.disableVersioning),
 });

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

@@ -25,6 +25,7 @@ export interface PluginOptions extends MetadataOptions, PathOptions {
   remarkPlugins: ([Function, object] | Function)[];
   rehypePlugins: string[];
   admonitions: any;
+  disableVersioning: boolean;
   excludeNextVersionDocs: boolean;
 }
 

website/docs/using-plugins.md

@@ -96,12 +96,16 @@ module.exports = {
 Then in the folder `my-plugin` you can create an index.js such as this
 
 ```js title="index.js"
-module.exports = function(context, options) {
+module.exports = function (context, options) {
   // ...
   return {
     name: 'my-docusaurus-plugin',
-    async loadContent() { ... },
+    async loadContent() {
-    async contentLoaded({content, actions}) { ... },
+      /* ... */
+    },
+    async contentLoaded({content, actions}) {
+      /* ... */
+    },
     /* other lifecycle API */
   };
 };
@@ -113,7 +117,7 @@ The `my-plugin` folder could also be a fully fledged package with it's own packa
 
 `context` is plugin-agnostic and the same object will be passed into all plugins used for a Docusaurus website. The `context` object contains the following fields:
 
-```js
+```ts
 interface LoadContext {
   siteDir: string;
   generatedFilesDir: string;
@@ -288,6 +292,11 @@ module.exports = {
          * Whether to display the last date the doc was updated.
          */
         showLastUpdateTime: false,
+        /**
+         * By default, versioning is enabled on versioned sites.
+         * This is a way to explicitly disable the versioning feature.
+         */
+        disableVersioning: false,
         /**
          * Skip the next release docs when versioning is enabled.
          * This will not generate HTML files in the production build for documents

website/docusaurus.config.js

@@ -63,6 +63,7 @@ module.exports = {
           showLastUpdateAuthor: true,
           showLastUpdateTime: true,
           remarkPlugins: [require('./src/plugins/remark-npm2yarn')],
+          disableVersioning: !!process.env.DISABLE_VERSIONING,
         },
         blog: {
           path: '../website-1.x/blog',