@docusaurus/plugin-content-docs 2.0.0-beta.8bda3b2db → 2.0.0-beta.9

package/src/__tests__/versions.test.ts

@@ -21,6 +21,7 @@ const DefaultI18N: I18n = {
   currentLocale: 'en',
   locales: ['en'],
   defaultLocale: 'en',
+  localeConfigs: {},
 };
 
 describe('version paths', () => {
@@ -76,9 +77,13 @@ describe('simple site', () => {
       isLast: true,
       routePriority: -1,
       sidebarFilePath: undefined,
+      tagsPath: '/docs/tags',
       versionLabel: 'Next',
       versionName: 'current',
       versionPath: '/docs',
+      versionBanner: null,
+      versionBadge: false,
+      versionClassName: 'docs-version-current',
     };
     return {simpleSiteDir, defaultOptions, defaultContext, vCurrent};
   }
@@ -109,6 +114,7 @@ describe('simple site', () => {
       {
         ...vCurrent,
         versionPath: '/myBaseUrl/docs',
+        tagsPath: '/myBaseUrl/docs/tags',
       },
     ]);
   });
@@ -139,6 +145,7 @@ describe('simple site', () => {
         versionLabel: 'current-label',
         routePriority: undefined,
         sidebarFilePath: undefined,
+        tagsPath: '/myBaseUrl/docs/current-path/tags',
         versionEditUrl: undefined,
         versionEditUrlLocalized: undefined,
       },
@@ -230,9 +237,13 @@ describe('versioned site, pluginId=default', () => {
       isLast: false,
       routePriority: undefined,
       sidebarFilePath: path.join(versionedSiteDir, 'sidebars.json'),
+      tagsPath: '/docs/next/tags',
       versionLabel: 'Next',
       versionName: 'current',
       versionPath: '/docs/next',
+      versionBanner: 'unreleased',
+      versionBadge: true,
+      versionClassName: 'docs-version-current',
     };
 
     const v101: VersionMetadata = {
@@ -247,9 +258,13 @@ describe('versioned site, pluginId=default', () => {
         versionedSiteDir,
         'versioned_sidebars/version-1.0.1-sidebars.json',
       ),
+      tagsPath: '/docs/tags',
       versionLabel: '1.0.1',
       versionName: '1.0.1',
       versionPath: '/docs',
+      versionBanner: null,
+      versionBadge: true,
+      versionClassName: 'docs-version-1.0.1',
     };
 
     const v100: VersionMetadata = {
@@ -264,9 +279,13 @@ describe('versioned site, pluginId=default', () => {
         versionedSiteDir,
         'versioned_sidebars/version-1.0.0-sidebars.json',
       ),
+      tagsPath: '/docs/1.0.0/tags',
       versionLabel: '1.0.0',
       versionName: '1.0.0',
       versionPath: '/docs/1.0.0',
+      versionBanner: 'unmaintained',
+      versionBadge: true,
+      versionClassName: 'docs-version-1.0.0',
     };
 
     const vwithSlugs: VersionMetadata = {
@@ -284,9 +303,13 @@ describe('versioned site, pluginId=default', () => {
         versionedSiteDir,
         'versioned_sidebars/version-withSlugs-sidebars.json',
       ),
+      tagsPath: '/docs/withSlugs/tags',
       versionLabel: 'withSlugs',
       versionName: 'withSlugs',
       versionPath: '/docs/withSlugs',
+      versionBanner: 'unmaintained',
+      versionBadge: true,
+      versionClassName: 'docs-version-withSlugs',
     };
 
     return {
@@ -301,14 +324,8 @@ describe('versioned site, pluginId=default', () => {
   }
 
   test('readVersionsMetadata versioned site', async () => {
-    const {
-      defaultOptions,
-      defaultContext,
-      vCurrent,
-      v101,
-      v100,
-      vwithSlugs,
-    } = await loadSite();
+    const {defaultOptions, defaultContext, vCurrent, v101, v100, vwithSlugs} =
+      await loadSite();
 
     const versionsMetadata = readVersionsMetadata({
       options: defaultOptions,
@@ -319,13 +336,8 @@ describe('versioned site, pluginId=default', () => {
   });
 
   test('readVersionsMetadata versioned site with includeCurrentVersion=false', async () => {
-    const {
-      defaultOptions,
-      defaultContext,
-      v101,
-      v100,
-      vwithSlugs,
-    } = await loadSite();
+    const {defaultOptions, defaultContext, v101, v100, vwithSlugs} =
+      await loadSite();
 
     const versionsMetadata = readVersionsMetadata({
       options: {...defaultOptions, includeCurrentVersion: false},
@@ -341,14 +353,8 @@ describe('versioned site, pluginId=default', () => {
   });
 
   test('readVersionsMetadata versioned site with version options', async () => {
-    const {
-      defaultOptions,
-      defaultContext,
-      vCurrent,
-      v101,
-      v100,
-      vwithSlugs,
-    } = await loadSite();
+    const {defaultOptions, defaultContext, vCurrent, v101, v100, vwithSlugs} =
+      await loadSite();
 
     const versionsMetadata = readVersionsMetadata({
       options: {
@@ -357,9 +363,13 @@ describe('versioned site, pluginId=default', () => {
         versions: {
           current: {
             path: 'current-path',
+            banner: 'unmaintained',
+            badge: false,
+            className: 'custom-current-className',
           },
           '1.0.0': {
             label: '1.0.0-label',
+            banner: 'unreleased',
           },
         },
       },
@@ -367,38 +377,43 @@ describe('versioned site, pluginId=default', () => {
     });
 
     expect(versionsMetadata).toEqual([
-      {...vCurrent, versionPath: '/docs/current-path'},
+      {
+        ...vCurrent,
+        tagsPath: '/docs/current-path/tags',
+        versionPath: '/docs/current-path',
+        versionBanner: 'unmaintained',
+        versionBadge: false,
+        versionClassName: 'custom-current-className',
+      },
       {
         ...v101,
         isLast: false,
         routePriority: undefined,
+        tagsPath: '/docs/1.0.1/tags',
         versionPath: '/docs/1.0.1',
+        versionBanner: 'unreleased',
       },
       {
         ...v100,
         isLast: true,
         routePriority: -1,
+        tagsPath: '/docs/tags',
         versionLabel: '1.0.0-label',
         versionPath: '/docs',
+        versionBanner: 'unreleased',
       },
       vwithSlugs,
     ]);
   });
 
   test('readVersionsMetadata versioned site with editUrl', async () => {
-    const {
-      defaultOptions,
-      defaultContext,
-      vCurrent,
-      v101,
-      v100,
-      vwithSlugs,
-    } = await loadSite();
+    const {defaultOptions, defaultContext, vCurrent, v101, v100, vwithSlugs} =
+      await loadSite();
 
     const versionsMetadata = readVersionsMetadata({
       options: {
         ...defaultOptions,
-        editUrl: 'https://github.com/facebook/docusaurus/edit/master/website/',
+        editUrl: 'https://github.com/facebook/docusaurus/edit/main/website/',
       },
       context: defaultContext,
     });
@@ -407,48 +422,42 @@ describe('versioned site, pluginId=default', () => {
       {
         ...vCurrent,
         versionEditUrl:
-          'https://github.com/facebook/docusaurus/edit/master/website/docs',
+          'https://github.com/facebook/docusaurus/edit/main/website/docs',
         versionEditUrlLocalized:
-          'https://github.com/facebook/docusaurus/edit/master/website/i18n/en/docusaurus-plugin-content-docs/current',
+          'https://github.com/facebook/docusaurus/edit/main/website/i18n/en/docusaurus-plugin-content-docs/current',
       },
       {
         ...v101,
         versionEditUrl:
-          'https://github.com/facebook/docusaurus/edit/master/website/versioned_docs/version-1.0.1',
+          'https://github.com/facebook/docusaurus/edit/main/website/versioned_docs/version-1.0.1',
         versionEditUrlLocalized:
-          'https://github.com/facebook/docusaurus/edit/master/website/i18n/en/docusaurus-plugin-content-docs/version-1.0.1',
+          'https://github.com/facebook/docusaurus/edit/main/website/i18n/en/docusaurus-plugin-content-docs/version-1.0.1',
       },
       {
         ...v100,
         versionEditUrl:
-          'https://github.com/facebook/docusaurus/edit/master/website/versioned_docs/version-1.0.0',
+          'https://github.com/facebook/docusaurus/edit/main/website/versioned_docs/version-1.0.0',
         versionEditUrlLocalized:
-          'https://github.com/facebook/docusaurus/edit/master/website/i18n/en/docusaurus-plugin-content-docs/version-1.0.0',
+          'https://github.com/facebook/docusaurus/edit/main/website/i18n/en/docusaurus-plugin-content-docs/version-1.0.0',
       },
       {
         ...vwithSlugs,
         versionEditUrl:
-          'https://github.com/facebook/docusaurus/edit/master/website/versioned_docs/version-withSlugs',
+          'https://github.com/facebook/docusaurus/edit/main/website/versioned_docs/version-withSlugs',
         versionEditUrlLocalized:
-          'https://github.com/facebook/docusaurus/edit/master/website/i18n/en/docusaurus-plugin-content-docs/version-withSlugs',
+          'https://github.com/facebook/docusaurus/edit/main/website/i18n/en/docusaurus-plugin-content-docs/version-withSlugs',
       },
     ]);
   });
 
   test('readVersionsMetadata versioned site with editUrl and editCurrentVersion=true', async () => {
-    const {
-      defaultOptions,
-      defaultContext,
-      vCurrent,
-      v101,
-      v100,
-      vwithSlugs,
-    } = await loadSite();
+    const {defaultOptions, defaultContext, vCurrent, v101, v100, vwithSlugs} =
+      await loadSite();
 
     const versionsMetadata = readVersionsMetadata({
       options: {
         ...defaultOptions,
-        editUrl: 'https://github.com/facebook/docusaurus/edit/master/website/',
+        editUrl: 'https://github.com/facebook/docusaurus/edit/main/website/',
         editCurrentVersion: true,
       },
       context: defaultContext,
@@ -458,30 +467,30 @@ describe('versioned site, pluginId=default', () => {
       {
         ...vCurrent,
         versionEditUrl:
-          'https://github.com/facebook/docusaurus/edit/master/website/docs',
+          'https://github.com/facebook/docusaurus/edit/main/website/docs',
         versionEditUrlLocalized:
-          'https://github.com/facebook/docusaurus/edit/master/website/i18n/en/docusaurus-plugin-content-docs/current',
+          'https://github.com/facebook/docusaurus/edit/main/website/i18n/en/docusaurus-plugin-content-docs/current',
       },
       {
         ...v101,
         versionEditUrl:
-          'https://github.com/facebook/docusaurus/edit/master/website/docs',
+          'https://github.com/facebook/docusaurus/edit/main/website/docs',
         versionEditUrlLocalized:
-          'https://github.com/facebook/docusaurus/edit/master/website/i18n/en/docusaurus-plugin-content-docs/current',
+          'https://github.com/facebook/docusaurus/edit/main/website/i18n/en/docusaurus-plugin-content-docs/current',
       },
       {
         ...v100,
         versionEditUrl:
-          'https://github.com/facebook/docusaurus/edit/master/website/docs',
+          'https://github.com/facebook/docusaurus/edit/main/website/docs',
         versionEditUrlLocalized:
-          'https://github.com/facebook/docusaurus/edit/master/website/i18n/en/docusaurus-plugin-content-docs/current',
+          'https://github.com/facebook/docusaurus/edit/main/website/i18n/en/docusaurus-plugin-content-docs/current',
       },
       {
         ...vwithSlugs,
         versionEditUrl:
-          'https://github.com/facebook/docusaurus/edit/master/website/docs',
+          'https://github.com/facebook/docusaurus/edit/main/website/docs',
         versionEditUrlLocalized:
-          'https://github.com/facebook/docusaurus/edit/master/website/i18n/en/docusaurus-plugin-content-docs/current',
+          'https://github.com/facebook/docusaurus/edit/main/website/i18n/en/docusaurus-plugin-content-docs/current',
       },
     ]);
   });
@@ -510,7 +519,15 @@ describe('versioned site, pluginId=default', () => {
     });
 
     expect(versionsMetadata).toEqual([
-      {...vCurrent, isLast: true, routePriority: -1, versionPath: '/docs'},
+      {
+        ...vCurrent,
+        isLast: true,
+        routePriority: -1,
+        tagsPath: '/docs/tags',
+        versionPath: '/docs',
+        versionBanner: null,
+        versionBadge: false,
+      },
     ]);
   });
 
@@ -628,9 +645,13 @@ describe('versioned site, pluginId=community', () => {
       isLast: false,
       routePriority: undefined,
       sidebarFilePath: path.join(versionedSiteDir, 'sidebars.json'),
+      tagsPath: '/communityBasePath/next/tags',
       versionLabel: 'Next',
       versionName: 'current',
       versionPath: '/communityBasePath/next',
+      versionBanner: 'unreleased',
+      versionBadge: true,
+      versionClassName: 'docs-version-current',
     };
 
     const v100: VersionMetadata = {
@@ -648,9 +669,13 @@ describe('versioned site, pluginId=community', () => {
         versionedSiteDir,
         'community_versioned_sidebars/version-1.0.0-sidebars.json',
       ),
+      tagsPath: '/communityBasePath/tags',
       versionLabel: '1.0.0',
       versionName: '1.0.0',
       versionPath: '/communityBasePath',
+      versionBanner: null,
+      versionBadge: true,
+      versionClassName: 'docs-version-1.0.0',
     };
 
     return {versionedSiteDir, defaultOptions, defaultContext, vCurrent, v100};
@@ -677,7 +702,7 @@ describe('versioned site, pluginId=community', () => {
 
     expect(versionsMetadata).toEqual([
       // vCurrent removed
-      v100,
+      {...v100, versionBadge: false},
     ]);
   });
 
@@ -694,7 +719,10 @@ describe('versioned site, pluginId=community', () => {
         ...vCurrent,
         isLast: true,
         routePriority: -1,
+        tagsPath: '/communityBasePath/tags',
         versionPath: '/communityBasePath',
+        versionBanner: null,
+        versionBadge: false,
       },
     ]);
   });

package/src/cli.ts

@@ -12,12 +12,10 @@ import {
 } from './versions';
 import fs from 'fs-extra';
 import path from 'path';
-import {
-  PathOptions,
-  UnprocessedSidebarItem,
-  UnprocessedSidebars,
-} from './types';
-import {loadSidebars, resolveSidebarPathOption} from './sidebars';
+import type {PathOptions, SidebarOptions} from './types';
+import {transformSidebarItems} from './sidebars/utils';
+import type {SidebarItem, NormalizedSidebars, Sidebar} from './sidebars/types';
+import {loadUnprocessedSidebars, resolveSidebarPathOption} from './sidebars';
 import {DEFAULT_PLUGIN_ID} from '@docusaurus/core/lib/constants';
 
 function createVersionedSidebarFile({
@@ -25,14 +23,16 @@ function createVersionedSidebarFile({
   pluginId,
   sidebarPath,
   version,
+  options,
 }: {
   siteDir: string;
   pluginId: string;
   sidebarPath: string | false | undefined;
   version: string;
+  options: SidebarOptions;
 }) {
   // Load current sidebar and create a new versioned sidebars file (if needed).
-  const loadedSidebars = loadSidebars(sidebarPath);
+  const loadedSidebars = loadUnprocessedSidebars(sidebarPath, options);
 
   // Do not create a useless versioned sidebars file if sidebars file is empty or sidebars are disabled/false)
   const shouldCreateVersionedSidebarFile =
@@ -42,30 +42,27 @@ function createVersionedSidebarFile({
     // TODO @slorber: this "version prefix" in versioned sidebars looks like a bad idea to me
     // TODO try to get rid of it
     // Transform id in original sidebar to versioned id.
-    const normalizeItem = (
-      item: UnprocessedSidebarItem,
-    ): UnprocessedSidebarItem => {
-      switch (item.type) {
-        case 'category':
-          return {...item, items: item.items.map(normalizeItem)};
-        case 'ref':
-        case 'doc':
-          return {
-            type: item.type,
-            id: `version-${version}/${item.id}`,
-          };
-        default:
-          return item;
+    const prependVersion = (item: SidebarItem): SidebarItem => {
+      if (item.type === 'ref' || item.type === 'doc') {
+        return {
+          type: item.type,
+          id: `version-${version}/${item.id}`,
+        };
       }
+      return item;
     };
 
-    const versionedSidebar: UnprocessedSidebars = Object.entries(
-      loadedSidebars,
-    ).reduce((acc: UnprocessedSidebars, [sidebarId, sidebarItems]) => {
-      const newVersionedSidebarId = `version-${version}/${sidebarId}`;
-      acc[newVersionedSidebarId] = sidebarItems.map(normalizeItem);
-      return acc;
-    }, {});
+    const versionedSidebar = Object.entries(loadedSidebars).reduce(
+      (acc: NormalizedSidebars, [sidebarId, sidebar]) => {
+        const versionedId = `version-${version}/${sidebarId}`;
+        acc[versionedId] = transformSidebarItems(
+          sidebar as Sidebar,
+          prependVersion,
+        );
+        return acc;
+      },
+      {},
+    );
 
     const versionedSidebarsDir = getVersionedSidebarsDirPath(siteDir, pluginId);
     const newSidebarFile = path.join(
@@ -82,12 +79,11 @@ function createVersionedSidebarFile({
 }
 
 // Tests depend on non-default export for mocking.
-// eslint-disable-next-line import/prefer-default-export
 export function cliDocsVersionCommand(
   version: string | null | undefined,
   siteDir: string,
   pluginId: string,
-  options: PathOptions,
+  options: PathOptions & SidebarOptions,
 ): void {
   // It wouldn't be very user-friendly to show a [default] log prefix,
   // so we use [docs] instead of [default]
@@ -159,6 +155,7 @@ export function cliDocsVersionCommand(
     pluginId,
     version,
     sidebarPath: resolveSidebarPathOption(siteDir, sidebarPath),
+    options,
   });
 
   // Update versions.json file.

package/src/client/__tests__/docsClientUtils.test.ts

@@ -350,14 +350,13 @@ describe('docsClientUtils', () => {
       latestVersionSuggestion: version2,
     });
 
-    // nothing to suggest, we are already on latest version
     expect(getDocVersionSuggestions(data, '/docs/')).toEqual({
-      latestDocSuggestion: undefined,
-      latestVersionSuggestion: undefined,
+      latestDocSuggestion: version2.docs[0],
+      latestVersionSuggestion: version2,
     });
     expect(getDocVersionSuggestions(data, '/docs/doc2')).toEqual({
-      latestDocSuggestion: undefined,
-      latestVersionSuggestion: undefined,
+      latestDocSuggestion: version2.docs[1],
+      latestVersionSuggestion: version2,
     });
 
     expect(getDocVersionSuggestions(data, '/docs/version1/')).toEqual({

package/src/client/docsClientUtils.ts

@@ -20,22 +20,11 @@ export type ActivePlugin = {
   pluginData: GlobalPluginData;
 };
 
-export type GetActivePluginOptions = {failfast?: boolean};
+export type GetActivePluginOptions = {failfast?: boolean}; // use fail-fast option if you know for sure one plugin instance is active
 
 // get the data of the plugin that is currently "active"
 // ie the docs of that plugin are currently browsed
 // it is useful to support multiple docs plugin instances
-export function getActivePlugin(
-  allPluginDatas: Record<string, GlobalPluginData>,
-  pathname: string,
-  options: {failfast: true}, // use fail-fast option if you know for sure one plugin instance is active
-): ActivePlugin;
-export function getActivePlugin(
-  allPluginDatas: Record<string, GlobalPluginData>,
-  pathname: string,
-  options?: GetActivePluginOptions,
-): ActivePlugin | undefined;
-
 export function getActivePlugin(
   allPluginDatas: Record<string, GlobalPluginData>,
   pathname: string,
@@ -140,10 +129,10 @@ export const getActiveDocContext = (
 };
 
 export type DocVersionSuggestions = {
+  // suggest the latest version
+  latestVersionSuggestion: GlobalVersion;
   // suggest the same doc, in latest version (if exist)
   latestDocSuggestion?: GlobalDoc;
-  // suggest the latest version
-  latestVersionSuggestion?: GlobalVersion;
 };
 
 export const getDocVersionSuggestions = (
@@ -152,17 +141,7 @@ export const getDocVersionSuggestions = (
 ): DocVersionSuggestions => {
   const latestVersion = getLatestVersion(data);
   const activeDocContext = getActiveDocContext(data, pathname);
-
-  // We only suggest another doc/version if user is not using the latest version
-  const isNotOnLatestVersion = activeDocContext.activeVersion !== latestVersion;
-
-  const latestDocSuggestion: GlobalDoc | undefined = isNotOnLatestVersion
-    ? activeDocContext?.alternateDocVersions[latestVersion.name]
-    : undefined;
-
-  const latestVersionSuggestion = isNotOnLatestVersion
-    ? latestVersion
-    : undefined;
-
-  return {latestDocSuggestion, latestVersionSuggestion};
+  const latestDocSuggestion: GlobalDoc | undefined =
+    activeDocContext?.alternateDocVersions[latestVersion.name];
+  return {latestDocSuggestion, latestVersionSuggestion: latestVersion};
 };

package/src/docFrontMatter.ts

@@ -5,11 +5,11 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-/* eslint-disable camelcase */
-
 import {
   JoiFrontMatter as Joi, // Custom instance for frontmatter
   URISchema,
+  FrontMatterTagsSchema,
+  FrontMatterTOCHeadingLevels,
   validateFrontMatter,
 } from '@docusaurus/utils-validation';
 import {DocFrontMatter} from './types';
@@ -28,10 +28,15 @@ const DocFrontMatterSchema = Joi.object<DocFrontMatter>({
   description: Joi.string().allow(''), // see  https://github.com/facebook/docusaurus/issues/4591#issuecomment-822372398
   slug: Joi.string(),
   sidebar_label: Joi.string(),
-  sidebar_position: Joi.number().min(0),
+  sidebar_position: Joi.number(),
+  sidebar_class_name: Joi.string(),
+  tags: FrontMatterTagsSchema,
   pagination_label: Joi.string(),
   custom_edit_url: URISchema.allow('', null),
   parse_number_prefixes: Joi.boolean(),
+  pagination_next: Joi.string().allow(null),
+  pagination_prev: Joi.string().allow(null),
+  ...FrontMatterTOCHeadingLevels,
 }).unknown();
 
 export function validateDocFrontMatter(