feat: new docs options: versions.{badge,className} (#5454)

* docs: add versions.{badge,className} options

* remove badge option test

.eslintrc.js

@@ -63,6 +63,7 @@ module.exports = {
     ],
     'jsx-a11y/click-events-have-key-events': WARNING,
     'jsx-a11y/no-noninteractive-element-interactions': WARNING,
+    'jsx-a11y/html-has-lang': OFF,
     'no-console': OFF,
     'no-else-return': OFF,
     'no-param-reassign': [WARNING, {props: false}],

packages/docusaurus-plugin-content-docs/src/__tests__/__snapshots__/index.test.ts.snap

@@ -515,6 +515,8 @@ Object {
   \\"version\\": \\"current\\",
   \\"label\\": \\"Next\\",
   \\"banner\\": \\"none\\",
+  \\"badge\\": false,
+  \\"className\\": \\"docs-version-current\\",
   \\"isLast\\": true,
   \\"docsSidebars\\": {
     \\"docs\\": [
@@ -1024,6 +1026,8 @@ Object {
   \\"version\\": \\"1.0.0\\",
   \\"label\\": \\"1.0.0\\",
   \\"banner\\": \\"none\\",
+  \\"badge\\": true,
+  \\"className\\": \\"docs-version-1.0.0\\",
   \\"isLast\\": true,
   \\"docsSidebars\\": {
     \\"version-1.0.0/community\\": [
@@ -1040,6 +1044,8 @@ Object {
   \\"version\\": \\"current\\",
   \\"label\\": \\"Next\\",
   \\"banner\\": \\"unreleased\\",
+  \\"badge\\": true,
+  \\"className\\": \\"docs-version-current\\",
   \\"isLast\\": false,
   \\"docsSidebars\\": {
     \\"community\\": [
@@ -1673,6 +1679,8 @@ Object {
   \\"version\\": \\"1.0.0\\",
   \\"label\\": \\"1.0.0\\",
   \\"banner\\": \\"unmaintained\\",
+  \\"badge\\": true,
+  \\"className\\": \\"docs-version-1.0.0\\",
   \\"isLast\\": false,
   \\"docsSidebars\\": {
     \\"version-1.0.0/docs\\": [
@@ -1715,6 +1723,8 @@ Object {
   \\"version\\": \\"1.0.1\\",
   \\"label\\": \\"1.0.1\\",
   \\"banner\\": \\"none\\",
+  \\"badge\\": true,
+  \\"className\\": \\"docs-version-1.0.1\\",
   \\"isLast\\": true,
   \\"docsSidebars\\": {
     \\"version-1.0.1/docs\\": [
@@ -1752,6 +1762,8 @@ Object {
   \\"version\\": \\"current\\",
   \\"label\\": \\"Next\\",
   \\"banner\\": \\"unreleased\\",
+  \\"badge\\": true,
+  \\"className\\": \\"docs-version-current\\",
   \\"isLast\\": false,
   \\"docsSidebars\\": {
     \\"docs\\": [
@@ -1789,6 +1801,8 @@ Object {
   \\"version\\": \\"withSlugs\\",
   \\"label\\": \\"withSlugs\\",
   \\"banner\\": \\"unmaintained\\",
+  \\"badge\\": true,
+  \\"className\\": \\"docs-version-withSlugs\\",
   \\"isLast\\": false,
   \\"docsSidebars\\": {
     \\"version-1.0.1/docs\\": [

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

@@ -82,6 +82,8 @@ describe('simple site', () => {
       versionName: 'current',
       versionPath: '/docs',
       versionBanner: 'none',
+      versionBadge: false,
+      versionClassName: 'docs-version-current',
     };
     return {simpleSiteDir, defaultOptions, defaultContext, vCurrent};
   }
@@ -240,6 +242,8 @@ describe('versioned site, pluginId=default', () => {
       versionName: 'current',
       versionPath: '/docs/next',
       versionBanner: 'unreleased',
+      versionBadge: true,
+      versionClassName: 'docs-version-current',
     };
 
     const v101: VersionMetadata = {
@@ -259,6 +263,8 @@ describe('versioned site, pluginId=default', () => {
       versionName: '1.0.1',
       versionPath: '/docs',
       versionBanner: 'none',
+      versionBadge: true,
+      versionClassName: 'docs-version-1.0.1',
     };
 
     const v100: VersionMetadata = {
@@ -278,6 +284,8 @@ describe('versioned site, pluginId=default', () => {
       versionName: '1.0.0',
       versionPath: '/docs/1.0.0',
       versionBanner: 'unmaintained',
+      versionBadge: true,
+      versionClassName: 'docs-version-1.0.0',
     };
 
     const vwithSlugs: VersionMetadata = {
@@ -300,6 +308,8 @@ describe('versioned site, pluginId=default', () => {
       versionName: 'withSlugs',
       versionPath: '/docs/withSlugs',
       versionBanner: 'unmaintained',
+      versionBadge: true,
+      versionClassName: 'docs-version-withSlugs',
     };
 
     return {
@@ -371,6 +381,8 @@ describe('versioned site, pluginId=default', () => {
           current: {
             path: 'current-path',
             banner: 'unmaintained',
+            badge: false,
+            className: 'custom-current-className',
           },
           '1.0.0': {
             label: '1.0.0-label',
@@ -387,6 +399,8 @@ describe('versioned site, pluginId=default', () => {
         tagsPath: '/docs/current-path/tags',
         versionPath: '/docs/current-path',
         versionBanner: 'unmaintained',
+        versionBadge: false,
+        versionClassName: 'custom-current-className',
       },
       {
         ...v101,
@@ -541,6 +555,7 @@ describe('versioned site, pluginId=default', () => {
         tagsPath: '/docs/tags',
         versionPath: '/docs',
         versionBanner: 'none',
+        versionBadge: false,
       },
     ]);
   });
@@ -664,6 +679,8 @@ describe('versioned site, pluginId=community', () => {
       versionName: 'current',
       versionPath: '/communityBasePath/next',
       versionBanner: 'unreleased',
+      versionBadge: true,
+      versionClassName: 'docs-version-current',
     };
 
     const v100: VersionMetadata = {
@@ -686,6 +703,8 @@ describe('versioned site, pluginId=community', () => {
       versionName: '1.0.0',
       versionPath: '/communityBasePath',
       versionBanner: 'none',
+      versionBadge: true,
+      versionClassName: 'docs-version-1.0.0',
     };
 
     return {versionedSiteDir, defaultOptions, defaultContext, vCurrent, v100};
@@ -712,7 +731,7 @@ describe('versioned site, pluginId=community', () => {
 
     expect(versionsMetadata).toEqual([
       // vCurrent removed
-      v100,
+      {...v100, versionBadge: false},
     ]);
   });
 
@@ -732,6 +751,7 @@ describe('versioned site, pluginId=community', () => {
         tagsPath: '/communityBasePath/tags',
         versionPath: '/communityBasePath',
         versionBanner: 'none',
+        versionBadge: false,
       },
     ]);
   });

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

@@ -56,6 +56,8 @@ const VersionOptionsSchema = Joi.object({
   path: Joi.string().allow('').optional(),
   label: Joi.string().optional(),
   banner: Joi.string().equal('none', 'unreleased', 'unmaintained').optional(),
+  badge: Joi.boolean().optional(),
+  className: Joi.string().optional(),
 });
 
 const VersionsOptionsSchema = Joi.object()

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

@@ -18,6 +18,8 @@ declare module '@docusaurus/plugin-content-docs-types' {
     version: string;
     label: string;
     banner: VersionBanner;
+    badge: boolean;
+    className: string;
     isLast: boolean;
     docsSidebars: PropSidebars;
   };

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

@@ -79,6 +79,8 @@ export function toVersionMetadataProp(
     version: loadedVersion.versionName,
     label: loadedVersion.versionLabel,
     banner: loadedVersion.versionBanner,
+    badge: loadedVersion.versionBadge,
+    className: loadedVersion.versionClassName,
     isLast: loadedVersion.isLast,
     docsSidebars: toSidebarsProp(loadedVersion),
   };

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

@@ -33,6 +33,8 @@ export type VersionMetadata = ContentPaths & {
   versionEditUrl?: string | undefined;
   versionEditUrlLocalized?: string | undefined;
   versionBanner: VersionBanner;
+  versionBadge: boolean;
+  versionClassName: string;
   isLast: boolean;
   sidebarFilePath: string | false | undefined; // versioned_sidebars/1.0.0.json
   routePriority: number | undefined; // -1 for the latest docs
@@ -69,6 +71,8 @@ export type VersionOptions = {
   path?: string;
   label?: string;
   banner?: VersionBanner;
+  badge?: boolean;
+  className?: string;
 };
 
 export type VersionsOptions = {

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

@@ -304,6 +304,35 @@ function getVersionBanner({
   );
 }
 
+function getVersionBadge({
+  versionName,
+  versionNames,
+  options,
+}: {
+  versionName: string;
+  versionNames: string[];
+  options: Pick<PluginOptions, 'versions'>;
+}): boolean {
+  const versionBadgeOption = options.versions[versionName]?.badge;
+  // If site is not versioned or only one version is included
+  // we don't show the version badge by default
+  // See https://github.com/facebook/docusaurus/issues/3362
+  const versionBadgeDefault = versionNames.length !== 1;
+  return versionBadgeOption ?? versionBadgeDefault;
+}
+
+function getVersionClassName({
+  versionName,
+  options,
+}: {
+  versionName: string;
+  options: Pick<PluginOptions, 'versions'>;
+}): string {
+  const versionClassNameOption = options.versions[versionName]?.className;
+  const versionClassNameDefault = `docs-version-${versionName}`;
+  return versionClassNameOption ?? versionClassNameDefault;
+}
+
 function createVersionMetadata({
   versionName,
   versionNames,
@@ -387,6 +416,8 @@ function createVersionMetadata({
       lastVersionName,
       options,
     }),
+    versionBadge: getVersionBadge({versionName, versionNames, options}),
+    versionClassName: getVersionClassName({versionName, options}),
     isLast,
     routePriority,
     sidebarFilePath,

packages/docusaurus-theme-classic/src/theme/DocItem/index.tsx

@@ -8,7 +8,6 @@
 import React from 'react';
 import clsx from 'clsx';
 
-import {useActivePlugin, useVersions} from '@theme/hooks/useDocs';
 import useWindowSize from '@theme/hooks/useWindowSize';
 import DocPaginator from '@theme/DocPaginator';
 import DocVersionBanner from '@theme/DocVersionBanner';
@@ -33,14 +32,6 @@ export default function DocItem(props: Props): JSX.Element {
   } = frontMatter;
   const {description, title} = metadata;
 
-  const {pluginId} = useActivePlugin({failfast: true})!;
-  const versions = useVersions(pluginId);
-
-  // If site is not versioned or only one version is included
-  // we don't show the version badge
-  // See https://github.com/facebook/docusaurus/issues/3362
-  const showVersionBadge = versions.length > 1;
-
   // We only add a title if:
   // - user asks to hide it with frontmatter
   // - the markdown content does not already contain a top-level h1 heading
@@ -67,7 +58,7 @@ export default function DocItem(props: Props): JSX.Element {
           <DocVersionBanner versionMetadata={versionMetadata} />
           <div className={styles.docItemContainer}>
             <article>
-              {showVersionBadge && (
+              {versionMetadata.badge && (
                 <span
                   className={clsx(
                     ThemeClassNames.docs.docVersionBadge,

packages/docusaurus-theme-classic/src/theme/DocPage/index.tsx

@@ -24,6 +24,7 @@ import {translate} from '@docusaurus/Translate';
 import clsx from 'clsx';
 import styles from './styles.module.css';
 import {ThemeClassNames, docVersionSearchTag} from '@docusaurus/theme-common';
+import Head from '@docusaurus/Head';
 
 type DocPageContentProps = {
   readonly currentDocRoute: DocumentRoute;
@@ -150,11 +151,17 @@ function DocPage(props: Props): JSX.Element {
     return <NotFound {...props} />;
   }
   return (
+    <>
+      <Head>
+        {/* TODO we should add a core addRoute({htmlClassName}) generic plugin option */}
+        <html className={versionMetadata.className} />
+      </Head>
       <DocPageContent
         currentDocRoute={currentDocRoute}
         versionMetadata={versionMetadata}>
         {renderRoutes(docRoutes, {versionMetadata})}
       </DocPageContent>
+    </>
   );
 }
 

website/docs/api/plugins/plugin-content-docs.md

@@ -91,6 +91,8 @@ type Versions = Record<
     label: string; // the label of the version
     path: string; // the route path of the version
     banner: 'none' | 'unreleased' | 'unmaintained'; // the banner to show at the top of a doc of that version
+    badge: boolean; // show a badge with the version name at the top of a doc of that version
+    className; // add a custom className to the <html> element when browsing docs of that version
   }
 >;
 ```

website/docusaurus.config.js

@@ -257,7 +257,7 @@ const TwitterSvg =
               : undefined,
           versions: {
             current: {
-              label: `${getNextBetaVersionName()} 🚧`,
+              label: `ho ${getNextBetaVersionName()} 🚧`,
             },
           },
         },