From 42e70e6d422412fa9b7fddb41fb35d0541306181 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9bastien=20Lorber?= Date: Tue, 31 Aug 2021 15:40:37 +0200 Subject: [PATCH] feat: new docs options: versions.{badge,className} (#5454) * docs: add versions.{badge,className} options * remove badge option test --- .eslintrc.js | 1 + .../__snapshots__/index.test.ts.snap | 14 +++++++++ .../src/__tests__/versions.test.ts | 22 ++++++++++++- .../src/options.ts | 2 ++ .../src/plugin-content-docs.d.ts | 2 ++ .../src/props.ts | 2 ++ .../src/types.ts | 4 +++ .../src/versions.ts | 31 +++++++++++++++++++ .../src/theme/DocItem/index.tsx | 11 +------ .../src/theme/DocPage/index.tsx | 17 +++++++--- .../docs/api/plugins/plugin-content-docs.md | 2 ++ website/docusaurus.config.js | 2 +- 12 files changed, 93 insertions(+), 17 deletions(-) diff --git a/.eslintrc.js b/.eslintrc.js index 137615d4a4..3cd3bc0255 100644 --- a/.eslintrc.js +++ b/.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}], diff --git a/packages/docusaurus-plugin-content-docs/src/__tests__/__snapshots__/index.test.ts.snap b/packages/docusaurus-plugin-content-docs/src/__tests__/__snapshots__/index.test.ts.snap index 0400a366e4..7e67c5144d 100644 --- a/packages/docusaurus-plugin-content-docs/src/__tests__/__snapshots__/index.test.ts.snap +++ b/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\\": [ diff --git a/packages/docusaurus-plugin-content-docs/src/__tests__/versions.test.ts b/packages/docusaurus-plugin-content-docs/src/__tests__/versions.test.ts index fba76fd6da..0fad9a9217 100644 --- a/packages/docusaurus-plugin-content-docs/src/__tests__/versions.test.ts +++ b/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, }, ]); }); diff --git a/packages/docusaurus-plugin-content-docs/src/options.ts b/packages/docusaurus-plugin-content-docs/src/options.ts index 87b5dbe9b4..8e300b4493 100644 --- a/packages/docusaurus-plugin-content-docs/src/options.ts +++ b/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() diff --git a/packages/docusaurus-plugin-content-docs/src/plugin-content-docs.d.ts b/packages/docusaurus-plugin-content-docs/src/plugin-content-docs.d.ts index d64f5629f9..841ce29893 100644 --- a/packages/docusaurus-plugin-content-docs/src/plugin-content-docs.d.ts +++ b/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; }; diff --git a/packages/docusaurus-plugin-content-docs/src/props.ts b/packages/docusaurus-plugin-content-docs/src/props.ts index a8ec05977f..95b7378122 100644 --- a/packages/docusaurus-plugin-content-docs/src/props.ts +++ b/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), }; diff --git a/packages/docusaurus-plugin-content-docs/src/types.ts b/packages/docusaurus-plugin-content-docs/src/types.ts index 400da88f95..089b5bf84c 100644 --- a/packages/docusaurus-plugin-content-docs/src/types.ts +++ b/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 = { diff --git a/packages/docusaurus-plugin-content-docs/src/versions.ts b/packages/docusaurus-plugin-content-docs/src/versions.ts index 77284ea68b..d73b26faf5 100644 --- a/packages/docusaurus-plugin-content-docs/src/versions.ts +++ b/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; +}): 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; +}): 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, diff --git a/packages/docusaurus-theme-classic/src/theme/DocItem/index.tsx b/packages/docusaurus-theme-classic/src/theme/DocItem/index.tsx index 3a93804f52..18924918aa 100644 --- a/packages/docusaurus-theme-classic/src/theme/DocItem/index.tsx +++ b/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 {
- {showVersionBadge && ( + {versionMetadata.badge && ( ; } return ( - - {renderRoutes(docRoutes, {versionMetadata})} - + <> + + {/* TODO we should add a core addRoute({htmlClassName}) generic plugin option */} + + + + {renderRoutes(docRoutes, {versionMetadata})} + + ); } diff --git a/website/docs/api/plugins/plugin-content-docs.md b/website/docs/api/plugins/plugin-content-docs.md index 800526ce47..50ccfd5fe5 100644 --- a/website/docs/api/plugins/plugin-content-docs.md +++ b/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 element when browsing docs of that version } >; ``` diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js index 4c3a7a462e..38f12460c1 100644 --- a/website/docusaurus.config.js +++ b/website/docusaurus.config.js @@ -257,7 +257,7 @@ const TwitterSvg = : undefined, versions: { current: { - label: `${getNextBetaVersionName()} 🚧`, + label: `ho ${getNextBetaVersionName()} 🚧`, }, }, },