From a5b2b6056bb034121b6a1297fe1efeac0d1aa37b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9bastien=20Lorber?= Date: Wed, 1 Jul 2020 19:03:59 +0200 Subject: [PATCH] feat(v2): add disableVersioning config to docs plugin (#2989) * add disableVersioning config to docs plugin * fix test * fix test --- .../src/__tests__/env.test.ts | 7 +++++ .../src/__tests__/pluginOptionSchema.test.ts | 1 + .../docusaurus-plugin-content-docs/src/env.ts | 29 ++++++++++++------- .../src/index.ts | 2 +- .../src/pluginOptionSchema.ts | 2 ++ .../src/types.ts | 1 + website/docs/using-plugins.md | 17 ++++++++--- website/docusaurus.config.js | 1 + 8 files changed, 44 insertions(+), 16 deletions(-) diff --git a/packages/docusaurus-plugin-content-docs/src/__tests__/env.test.ts b/packages/docusaurus-plugin-content-docs/src/__tests__/env.test.ts index e5c93ffd6d..236242afc3 100644 --- a/packages/docusaurus-plugin-content-docs/src/__tests__/env.test.ts +++ b/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(() => { diff --git a/packages/docusaurus-plugin-content-docs/src/__tests__/pluginOptionSchema.test.ts b/packages/docusaurus-plugin-content-docs/src/__tests__/pluginOptionSchema.test.ts index 68cafdd88a..b9cd0e41a9 100644 --- a/packages/docusaurus-plugin-content-docs/src/__tests__/pluginOptionSchema.test.ts +++ b/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); diff --git a/packages/docusaurus-plugin-content-docs/src/env.ts b/packages/docusaurus-plugin-content-docs/src/env.ts index 13e9861c1c..19f3e8e4a4 100644 --- a/packages/docusaurus-plugin-content-docs/src/env.ts +++ b/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( - fs.readFileSync(versionsJSONFile, 'utf8'), - ); - if (parsedVersions && parsedVersions.length > 0) { - // eslint-disable-next-line prefer-destructuring - versioning.latestVersion = parsedVersions[0]; - versioning.enabled = true; - versioning.versions = parsedVersions; - versioning.docsDir = getVersionedDocsDir(siteDir); - versioning.sidebarsDir = getVersionedSidebarsDir(siteDir); + if (!options.disableVersioning) { + const parsedVersions = JSON.parse( + fs.readFileSync(versionsJSONFile, 'utf8'), + ); + if (parsedVersions && parsedVersions.length > 0) { + // eslint-disable-next-line prefer-destructuring + versioning.latestVersion = parsedVersions[0]; + versioning.enabled = true; + versioning.versions = parsedVersions; + versioning.docsDir = getVersionedDocsDir(siteDir); + versioning.sidebarsDir = getVersionedSidebarsDir(siteDir); + } } } diff --git a/packages/docusaurus-plugin-content-docs/src/index.ts b/packages/docusaurus-plugin-content-docs/src/index.ts index 4937c38537..23467c66e6 100644 --- a/packages/docusaurus-plugin-content-docs/src/index.ts +++ b/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, diff --git a/packages/docusaurus-plugin-content-docs/src/pluginOptionSchema.ts b/packages/docusaurus-plugin-content-docs/src/pluginOptionSchema.ts index 95edd762c5..1a95d4f298 100644 --- a/packages/docusaurus-plugin-content-docs/src/pluginOptionSchema.ts +++ b/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), }); diff --git a/packages/docusaurus-plugin-content-docs/src/types.ts b/packages/docusaurus-plugin-content-docs/src/types.ts index 5c0da4f43a..4825145a97 100644 --- a/packages/docusaurus-plugin-content-docs/src/types.ts +++ b/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; } diff --git a/website/docs/using-plugins.md b/website/docs/using-plugins.md index 16370db371..174f47a3e2 100644 --- a/website/docs/using-plugins.md +++ b/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 contentLoaded({content, actions}) { ... }, + async loadContent() { + /* ... */ + }, + 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 diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js index a1265a01fa..2190609052 100644 --- a/website/docusaurus.config.js +++ b/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',