From a4769e3f30b52428f7df8c0f69d4e1e46eb6f209 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9bastien=20Lorber?= Date: Tue, 1 Sep 2020 16:31:33 +0200 Subject: [PATCH] fix(v2): alpha 62 doc fixes (#3381) * deprecated nextVersionLabel option * useActivePlugin failfast option * remove deprecated option nextVersionLabel * routeBasePath: '' should be forbidden * routeBasePath: '' should be forbidden * Docs: do not show version badge if there is only 1 version: https://github.com/facebook/docusaurus/issues/3362 * allow sidebars file to not exist: fallback to empty sidebars https://githu.com/facebook/docusaurus/issues/3366 --- .../src/__tests__/sidebars.test.ts | 4 +++ .../client/__tests__/docsClientUtils.test.ts | 14 ++++++++ .../src/client/docsClientUtils.ts | 34 ++++++++++++++++--- .../src/sidebars.ts | 7 +++- .../src/theme/hooks/useDocs.ts | 5 +-- .../src/versions.ts | 9 +++-- .../src/__tests__/validateThemeConfig.test.js | 1 - .../src/theme/DocItem/index.tsx | 27 ++++++++------- .../src/theme/DocVersionSuggestions/index.tsx | 12 +------ .../src/validateThemeConfig.js | 1 - website/docusaurus.config.js | 1 - 11 files changed, 80 insertions(+), 35 deletions(-) diff --git a/packages/docusaurus-plugin-content-docs/src/__tests__/sidebars.test.ts b/packages/docusaurus-plugin-content-docs/src/__tests__/sidebars.test.ts index ec8f6fb4c36b..d46917e42a4b 100644 --- a/packages/docusaurus-plugin-content-docs/src/__tests__/sidebars.test.ts +++ b/packages/docusaurus-plugin-content-docs/src/__tests__/sidebars.test.ts @@ -115,9 +115,13 @@ describe('loadSidebars', () => { }); test('unexisting path', () => { + /* expect(() => loadSidebars('badpath')).toThrowErrorMatchingInlineSnapshot( `"No sidebar file exist at path: badpath"`, ); + */ + // See https://github.com/facebook/docusaurus/issues/3366 + expect(loadSidebars('badpath')).toEqual({}); }); test('undefined path', () => { diff --git a/packages/docusaurus-plugin-content-docs/src/client/__tests__/docsClientUtils.test.ts b/packages/docusaurus-plugin-content-docs/src/client/__tests__/docsClientUtils.test.ts index cf12adcd49c2..de41979a7bbc 100644 --- a/packages/docusaurus-plugin-content-docs/src/client/__tests__/docsClientUtils.test.ts +++ b/packages/docusaurus-plugin-content-docs/src/client/__tests__/docsClientUtils.test.ts @@ -32,6 +32,17 @@ describe('docsClientUtils', () => { expect(getActivePlugin(data, '/')).toEqual(undefined); expect(getActivePlugin(data, '/xyz')).toEqual(undefined); + expect(() => + getActivePlugin(data, '/', {failfast: true}), + ).toThrowErrorMatchingInlineSnapshot( + `"Can't find active docs plugin for pathname=/, while it was expected to be found. Maybe you tried to use a docs feature that can only be used on a docs-related page? Existing docs plugin paths are: /ios, /android"`, + ); + expect(() => + getActivePlugin(data, '/xyz', {failfast: true}), + ).toThrowErrorMatchingInlineSnapshot( + `"Can't find active docs plugin for pathname=/xyz, while it was expected to be found. Maybe you tried to use a docs feature that can only be used on a docs-related page? Existing docs plugin paths are: /ios, /android"`, + ); + const activePluginIos: ActivePlugin = { pluginId: 'pluginIosId', pluginData: data.pluginIosId, @@ -115,6 +126,9 @@ describe('docsClientUtils', () => { }, ], }; + + expect(getActiveVersion(data, '/someUnknownPath')).toEqual(undefined); + expect(getActiveVersion(data, '/docs/next')?.name).toEqual('next'); expect(getActiveVersion(data, '/docs/next/')?.name).toEqual('next'); expect(getActiveVersion(data, '/docs/next/someDoc')?.name).toEqual('next'); diff --git a/packages/docusaurus-plugin-content-docs/src/client/docsClientUtils.ts b/packages/docusaurus-plugin-content-docs/src/client/docsClientUtils.ts index 6adbc0d98511..7d2f9adff395 100644 --- a/packages/docusaurus-plugin-content-docs/src/client/docsClientUtils.ts +++ b/packages/docusaurus-plugin-content-docs/src/client/docsClientUtils.ts @@ -20,13 +20,27 @@ export type ActivePlugin = { pluginData: GlobalPluginData; }; +export type GetActivePluginOptions = {failfast?: boolean}; + // 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 const getActivePlugin = ( +export function getActivePlugin( + allPluginDatas: Record, + 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, + pathname: string, + options?: GetActivePluginOptions, +): ActivePlugin | undefined; + +export function getActivePlugin( allPluginDatas: Record, pathname: string, -): ActivePlugin | undefined => { + options: GetActivePluginOptions = {}, +): ActivePlugin | undefined { const activeEntry = Object.entries(allPluginDatas).find( ([_id, pluginData]) => { return !!matchPath(pathname, { @@ -37,10 +51,22 @@ export const getActivePlugin = ( }, ); - return activeEntry + const activePlugin: ActivePlugin | undefined = activeEntry ? {pluginId: activeEntry[0], pluginData: activeEntry[1]} : undefined; -}; + + if (!activePlugin && options.failfast) { + throw new Error( + `Can't find active docs plugin for pathname=${pathname}, while it was expected to be found. Maybe you tried to use a docs feature that can only be used on a docs-related page? Existing docs plugin paths are: ${Object.values( + allPluginDatas, + ) + .map((plugin) => plugin.path) + .join(', ')}`, + ); + } + + return activePlugin; +} export type ActiveDocContext = { activeVersion?: Version; diff --git a/packages/docusaurus-plugin-content-docs/src/sidebars.ts b/packages/docusaurus-plugin-content-docs/src/sidebars.ts index e2cbd02f6d6f..06e46d1c9967 100644 --- a/packages/docusaurus-plugin-content-docs/src/sidebars.ts +++ b/packages/docusaurus-plugin-content-docs/src/sidebars.ts @@ -200,9 +200,14 @@ export function loadSidebars(sidebarFilePath: string): Sidebars { if (!sidebarFilePath) { throw new Error(`sidebarFilePath not provided: ${sidebarFilePath}`); } + + // sidebars file is optional, some users use docs without sidebars! + // See https://github.com/facebook/docusaurus/issues/3366 if (!fs.existsSync(sidebarFilePath)) { - throw new Error(`No sidebar file exist at path: ${sidebarFilePath}`); + // throw new Error(`No sidebar file exist at path: ${sidebarFilePath}`); + return {}; } + // We don't want sidebars to be cached because of hot reloading. const sidebarJson = importFresh(sidebarFilePath) as SidebarsJSON; return normalizeSidebars(sidebarJson); diff --git a/packages/docusaurus-plugin-content-docs/src/theme/hooks/useDocs.ts b/packages/docusaurus-plugin-content-docs/src/theme/hooks/useDocs.ts index dccf871a0bce..eea342cbeb6d 100644 --- a/packages/docusaurus-plugin-content-docs/src/theme/hooks/useDocs.ts +++ b/packages/docusaurus-plugin-content-docs/src/theme/hooks/useDocs.ts @@ -18,6 +18,7 @@ import { getActiveVersion, getActiveDocContext, getDocVersionSuggestions, + GetActivePluginOptions, } from '../../client/docsClientUtils'; const useAllDocsData = (): Record => @@ -26,10 +27,10 @@ const useAllDocsData = (): Record => const useDocsData = (pluginId: string | undefined) => usePluginData('docusaurus-plugin-content-docs', pluginId) as GlobalPluginData; -export const useActivePlugin = () => { +export const useActivePlugin = (options: GetActivePluginOptions = {}) => { const data = useAllDocsData(); const {pathname} = useLocation(); - return getActivePlugin(data, pathname); + return getActivePlugin(data, pathname, options); }; // versions are returned ordered (most recent first) diff --git a/packages/docusaurus-plugin-content-docs/src/versions.ts b/packages/docusaurus-plugin-content-docs/src/versions.ts index 74495c3134ca..e546248f84f3 100644 --- a/packages/docusaurus-plugin-content-docs/src/versions.ts +++ b/packages/docusaurus-plugin-content-docs/src/versions.ts @@ -24,6 +24,7 @@ import {DEFAULT_PLUGIN_ID} from '@docusaurus/core/lib/constants'; import {LoadContext} from '@docusaurus/types'; import {normalizeUrl} from '@docusaurus/utils'; import {difference} from 'lodash'; +import chalk from 'chalk'; // retro-compatibility: no prefix for the default plugin id function addPluginIdPrefix(fileOrDir: string, pluginId: string): string { @@ -222,9 +223,13 @@ function checkVersionMetadataPaths({ `The docs folder does not exist for version [${versionName}]. A docs folder is expected to be found at ${docsDirPath}`, ); } + + // See https://github.com/facebook/docusaurus/issues/3366 if (!fs.existsSync(sidebarFilePath)) { - throw new Error( - `The sidebar file does not exist for version [${versionName}]. A sidebar file is expected to be found at ${sidebarFilePath}`, + console.log( + chalk.yellow( + `The sidebar file of docs version [${versionName}] does not exist. It is optional, but should rather be provided at ${sidebarFilePath}`, + ), ); } } diff --git a/packages/docusaurus-theme-classic/src/__tests__/validateThemeConfig.test.js b/packages/docusaurus-theme-classic/src/__tests__/validateThemeConfig.test.js index 06eea9f19a4b..a2f8a50db129 100644 --- a/packages/docusaurus-theme-classic/src/__tests__/validateThemeConfig.test.js +++ b/packages/docusaurus-theme-classic/src/__tests__/validateThemeConfig.test.js @@ -55,7 +55,6 @@ describe('themeConfig', () => { { type: 'docsVersionDropdown', position: 'left', - nextVersionLabel: '2.0.0-next', }, { to: 'docs/next/support', diff --git a/packages/docusaurus-theme-classic/src/theme/DocItem/index.tsx b/packages/docusaurus-theme-classic/src/theme/DocItem/index.tsx index 3cf5316c5ee8..2bd82f00d850 100644 --- a/packages/docusaurus-theme-classic/src/theme/DocItem/index.tsx +++ b/packages/docusaurus-theme-classic/src/theme/DocItem/index.tsx @@ -17,16 +17,11 @@ import TOC from '@theme/TOC'; import clsx from 'clsx'; import styles from './styles.module.css'; -import {useActivePlugin, useActiveVersion} from '@theme/hooks/useDocs'; - -// TODO can't we receive the version as props instead? -const useDocVersion = () => { - const version = useActiveVersion(useActivePlugin().pluginId); - if (!version) { - throw new Error("unexpected, can't get version data of doc"); // should not happen - } - return version; -}; +import { + useActivePlugin, + useVersions, + useActiveVersion, +} from '@theme/hooks/useDocs'; function DocItem(props: Props): JSX.Element { const {siteConfig = {}} = useDocusaurusContext(); @@ -49,7 +44,15 @@ function DocItem(props: Props): JSX.Element { hide_table_of_contents: hideTableOfContents, }, } = DocContent; - const version = useDocVersion(); + + const {pluginId} = useActivePlugin({failfast: true}); + const versions = useVersions(pluginId); + const version = useActiveVersion(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; const metaTitle = title ? `${title} | ${siteTitle}` : siteTitle; const metaImageUrl = useBaseUrl(metaImage, {absolute: true}); @@ -83,7 +86,7 @@ function DocItem(props: Props): JSX.Element {
- {version && ( + {showVersionBadge && (
Version: {version.label} diff --git a/packages/docusaurus-theme-classic/src/theme/DocVersionSuggestions/index.tsx b/packages/docusaurus-theme-classic/src/theme/DocVersionSuggestions/index.tsx index 05bf3e84260a..5d2168b1b2d0 100644 --- a/packages/docusaurus-theme-classic/src/theme/DocVersionSuggestions/index.tsx +++ b/packages/docusaurus-theme-classic/src/theme/DocVersionSuggestions/index.tsx @@ -14,16 +14,6 @@ import { useDocVersionSuggestions, } from '@theme/hooks/useDocs'; -const useMandatoryActiveDocsPluginId = () => { - const activePlugin = useActivePlugin(); - if (!activePlugin) { - throw new Error( - 'DocVersionCallout is only supposed to be used on docs-related routes', - ); - } - return activePlugin.pluginId; -}; - const getVersionMainDoc = (version) => version.docs.find((doc) => doc.id === version.mainDocId); @@ -31,7 +21,7 @@ function DocVersionSuggestions(): JSX.Element { const { siteConfig: {title: siteTitle}, } = useDocusaurusContext(); - const pluginId = useMandatoryActiveDocsPluginId(); + const {pluginId} = useActivePlugin({failfast: true}); const activeVersion = useActiveVersion(pluginId); const { latestDocSuggestion, diff --git a/packages/docusaurus-theme-classic/src/validateThemeConfig.js b/packages/docusaurus-theme-classic/src/validateThemeConfig.js index 7290fcdda290..7a35e103af69 100644 --- a/packages/docusaurus-theme-classic/src/validateThemeConfig.js +++ b/packages/docusaurus-theme-classic/src/validateThemeConfig.js @@ -56,7 +56,6 @@ const DocsVersionDropdownNavbarItemSchema = Joi.object({ type: Joi.string().equal('docsVersionDropdown').required(), position: NavbarItemPosition, docsPluginId: Joi.string(), - nextVersionLabel: Joi.string().default('Next'), // TODO remove soon }); // Can this be made easier? :/ diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js index 6ec8f7f83dd5..f49b1f7d65d3 100644 --- a/website/docusaurus.config.js +++ b/website/docusaurus.config.js @@ -250,7 +250,6 @@ module.exports = { { type: 'docsVersionDropdown', position: 'left', - nextVersionLabel: '2.0.0-next', }, {to: 'blog', label: 'Blog', position: 'left'}, {to: 'showcase', label: 'Showcase', position: 'left'},